Docusaurus is a static-site generator for technical documentation. It supports Markdown, MDX, navigation, search, themes, and plugins.

In this codelab, you create a Docusaurus site, add a documentation page, configure sidebar navigation, preview the site, and build it for production.

By the end, you will have:

Before you begin, make sure that you have the following tools:

To check your Node.js version:

Use the Docusaurus initializer to create a site from the classic preset.

  1. At the command prompt, create a Docusaurus project.
    npx create-docusaurus@latest my-docs-site classic
    
  2. When prompted to choose a language, do one of the following:
    • To use TypeScript, choose TypeScript.
    • To use JavaScript, choose JavaScript.
  3. When prompted to choose a package manager, do one of the following:
    • To use the default package manager, press Enter.
    • To use another package manager, select the package manager.
  4. Change to the project directory.
    cd my-docs-site
    
  5. Install the dependencies.
    npm install
    

The classic preset includes the docs plugin, blog plugin, and default theme.

Docusaurus keeps documentation content separate from site configuration.

The following folders contain the files that you edit most often:

Path

Purpose

docs/

Markdown and MDX documentation pages

src/pages/

Custom React pages, such as landing pages

static/

Static assets, such as images

The following files control site settings and navigation:

File

Purpose

docusaurus.config.ts

Site title, URL, plugins, and theme options

sidebars.ts

Docs sidebar navigation

src/css/custom.css

Global style overrides

To see how the generated site connects docs content to navigation:

The sidebars.ts file controls which pages appear in the left navigation.

Create a page in docs/, and then link to it from the intro page.

  1. In your code editor, create docs/getting-started.md.
  2. Add the following content to docs/getting-started.md.
    ---
    sidebar_position: 2
    ---
    
    # Getting started
    
    Welcome to the documentation site you created.
    
    This page is in the `docs/` folder and is rendered automatically by
    Docusaurus.
    
  3. In docs/intro.md, add a link to the new page.
    Read [Getting started](./getting-started).
    

The block between --- markers is front matter. In this example, sidebar_position controls the sort order among sibling pages.

To show the new page in the left navigation, update the sidebar configuration.

The string entries map to doc IDs that Docusaurus derives from filenames. The getting-started entry maps to docs/getting-started.md.

Start the development server to preview your changes with hot reload.

Docusaurus opens http://localhost:3000 in your browser. You should see:

To verify hot reload:

When you are ready to publish the site, create a production build.

  1. At the command prompt, create the production build.
    npm run build
    
    Docusaurus writes the output to the build/ directory.
  2. To verify the production build locally, start the local production server.
    npm run serve
    

You can deploy the contents of build/ to any static host.

Common static hosts include the following services:

To deploy manually:

For GitHub Pages, Docusaurus also provides a deploy script.

  1. In docusaurus.config.ts, set url and baseUrl to match your hosting target.
  2. At the command prompt, deploy the site.
    npm run deploy
    

You now have a working Docusaurus documentation site. What to do next: