Tutorials

A basic overview of how to create a new doc item in /docs. For more information and detailed guides, find the official Docs here https://docusaurus.io/docs.

Create a Document​

Documents are groups of pages connected through:

• a sidebar
• previous/next navigation
• versioning

Create your first Doc​

Create a Markdown file at 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:

---
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:

module.exports = {
    tutorialSidebar: [
        {
            type: 'category',
            label: 'Tutorial',
            items: ['hello'],
        },
    ],
};

Markdown Features​

Docusaurus supports Markdown and a few additional features.

Front Matter​

Markdown documents have metadata at the top called Front Matter:

---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---

## Markdown heading

Markdown text with [links](./hello.md)

Links​

Regular Markdown links are supported, using url paths or relative file paths.

Let's see the [docs](/docs/intro/).

Let's see the [docs](../docs/intro.mdx).

Result: Let's see the docs.

Images​

Regular Markdown images are supported.

You can use absolute paths to reference images in the static directory (static/img/docusaurus.png):

![Docusaurus logo](/img/docusaurus.png)

Code Blocks​

Markdown code blocks are supported with Syntax highlighting.

```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
    return (
        <h1>Hello, Docusaurus!</h1>
    )
}
```

function HelloDocusaurus() {
  return <h1>Hello, Docusaurus!</h1>;
}

Admonitions​

Docusaurus has a special syntax to create admonitions and callouts:

:::tip My tip

Use this awesome feature option

:::

:::danger Take care

This action is dangerous

:::

MDX and React Components​

MDX can make your documentation more interactive and allows using any React components inside Markdown:

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '20px',
      color: '#fff',
      padding: '10px',
      cursor: 'pointer',
    }}
    onClick={() => {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  </span>
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

This is Docusaurus green !

This is Facebook blue !

Manage Docs Versions​

Docusaurus can manage multiple versions of your docs.

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:

module.exports = {
    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