Docusaurus is essentially a set of npm packages.
- Node.js version >= 14 or above (which can be checked by running
node -v). You can use nvm for managing multiple Node versions on a single machine installed.
- When installing Node.js, you are recommended to check all checkboxes related to dependencies.
- Yarn version >= 1.5 (which can be checked by running
npmclient. It is not strictly necessary but highly encouraged.
Scaffold project website
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.
npx [email protected] [name] [template]
npx [email protected] website classic
If you do not specify
template, it will prompt you for them. We recommend the
classic template so that you can get started quickly, and it contains features found in Docusaurus 1. The
classic template contains
@docusaurus/preset-classic which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
template also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory.
If you are setting up a new Docusaurus website for a Facebook open source project, use the
npx [email protected] my-website facebook
If you want to skip installing dependencies, use the
--skip-install option, like the following:
npx [email protected] my-website classic --skip-install
You can also use the template's TypeScript variant by passing the
npx [email protected] my-website classic --typescript
Assuming you chose the classic template and named your site
my-website, you will see the following files generated under a new directory
│ ├── 2019-05-28-hola.md
│ ├── 2019-05-29-hello-world.md
│ └── 2020-05-30-welcome.md
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ └── mdx.md
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
│ └── img
Project structure rundown
/blog/- Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the blog guide
/docs/- Contains the Markdown files for the docs. Customize the order of the docs sidebar in
sidebars.js. More details can be found in the docs guide
/src/- Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files in here but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
/src/pages- Any files within this directory will be converted into a website page. More details can be found in the pages guide
/static/- Static directory. Any contents inside here will be copied into the root of the final
/docusaurus.config.js- A config file containing the site configuration. This is the equivalent of
siteConfig.jsin Docusaurus v1
/package.json- A Docusaurus website is a React app. You can install and use any npm packages you like in them
/sidebar.js- Used by the documentation to specify the order of documents in the sidebar
If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:
├── package-a # Another package, your actual project
│ ├── src
│ └── package.json # Package A's dependencies
├── website # Docusaurus root
│ ├── docs
│ ├── src
│ └── package.json # Docusaurus' dependencies
├── package.json # Monorepo's shared dependencies
In this case, you should run
npx create-docusaurus within the
If you're using a hosting provider such as Netlify or Vercel, you will need to change the
Base directory of the site to where your Docusaurus root is. In this case, that would be
./website. Read more about configuring ignore commands in the deployment docs.
Running the development server
To preview your changes as you edit the files, you can run a local development server that will serve your website and reflect the latest changes.
npm run start
yarn run start
By default, a browser window will open at http://localhost:3000.
Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.
Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:
npm run build
yarn run build
and contents will be generated within the
/build directory, which can be copied to any static file hosting service like GitHub pages, Vercel or Netlify. Check out the docs on deployment for more details.
Updating your Docusaurus version
There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in
package.json to the desired version. Note that all
@docusaurus/-namespaced packages should be using the same version.
Then, in the directory containing
package.json, run your package manager's install command:
To check that the update occurred successfully, run:
npx docusaurus --version
npx docusaurus --version
You should see the correct version as output.
Alternatively, if you are using Yarn, you can do:
Use new unreleased features of Docusaurus with the
@canary npm dist tag