Skip to main content

Create a Document

Documents are groups of pages connected through:

  • sidebar
  • previous/next navigation
  • versioning

Create your first Doc​

Create a Markdown file at docs/hello.md:

docs/hello.md
# Hello

This is my **first Docusaurus document**!

A new document is now available at http://localhost:3000/docs/hello.

Configure the Sidebar​

Docusaurus automatically creates a sidebar from the docs folder.

Add metadata to customize the sidebar label and position:

docs/hello.md
---
sidebar_label: "Hi!"
sidebar_position: 3
---

# Hello

This is my **first Docusaurus document**!

It is also possible to create your sidebar explicitly in sidebars.js:

sidebars.js
export default {
  tutorialSidebar: [
    "intro",
    "hello",
    {
      type: "category",
      label: "Tutorial",
      items: ["tutorial-basics/create-a-document"],
    },
  ],
};

Create a docs version​

Release a version 1.0 of your project:

npm run docusaurus docs:version 1.0

The docs folder is copied into versioned_docs/version-1.0 and versions.json is created.

Your docs now have 2 versions:

  • 1.0 at http://localhost:3000/docs/ for the version 1.0 docs
  • current at http://localhost:3000/docs/next/ for the upcoming, unreleased docs

Add a Version Dropdown​

To navigate seamlessly across versions, add a version dropdown.

Modify the docusaurus.config.js file:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'docsVersionDropdown',
        },
      ],
    },
  },
};

The docs version dropdown appears in your navbar:

Update an existing version​

It is possible to edit versioned docs in their respective folder:

  • versioned_docs/version-1.0/hello.md updates http://localhost:3000/docs/hello
  • docs/hello.md updates http://localhost:3000/docs/next/hello

Configure i18n​

Modify docusaurus.config.js to add support for the fr locale:

docusaurus.config.js
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
};

Translate a doc​

Copy the docs/intro.md file to the i18n/fr folder:

mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/

cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md

Translate i18n/fr/docusaurus-plugin-content-docs/current/intro.md in French.

Start your localized site​

Start your site on the French locale:

npm run start -- --locale fr

Your localized site is accessible at http://localhost:3000/fr/ and the Getting Started page is translated.

caution

In development, you can only use one locale at a time.

Add a Locale Dropdown​

To navigate seamlessly across languages, add a locale dropdown.

Modify the docusaurus.config.js file:

docusaurus.config.js
export default {
  themeConfig: {
    navbar: {
      items: [
        {
          type: 'localeDropdown',
        },
      ],
    },
  },
};

The locale dropdown now appears in your navbar:

Build your localized site​

Build your site for a specific locale:

npm run build -- --locale fr

Or build your site to include all the locales at once:

npm run build
Last updated on by Keith Tan