Skip to main content

Reference

Getting Started​

Docusaurus Docs

This reference guide only contains some of the most important stuff. Don't be afraid to look in the docs for more information, after all this is docusaurus!

CLI​

npx docusaurus help

So the key with the CLI is that you aren't actually running a "docusaurus" executable... you run npm run <command>, then you will see the output and the docusaurus <command> is then shown as one of the first outputs. (See the scripts section of package.json)... it's nothing special/external, just normal node.js scripts

Showcase​

Use the showcase for inspiration

Details​

Markdown can embed HTML elements, and details HTML elements are beautifully styled:

<details>
  <summary>Toggle me!</summary>
  <div>
    <div>This is the detailed content</div>
    <br/>
    <details>
      <summary>
        Nested toggle! Some surprise inside...
      </summary>
      <div>😲😲😲😲😲</div>
    </details>
  </div>
</details>
Toggle me!
This is the detailed content

Nested toggle! Some surprise inside...

😲😲😲😲😲

Components​

Must use MDX (Markdown for JSX), which allows you to use JSX (components) in your Markdown files.

Inline Component​

Define component in the same place it will be used

You cannot see the component definition when rendered, but it is right below this line and before usage

An inline component used here

Imported Component​

You cannot see the component import when rendered, but it is right below this line and before usage

An imported component used here

Pre-built Components​

Youtube Example

Additional Doc Features​

Headings and Table of Contents​

Explanation

Alerts​

Explanation

Codeblocks​

Explanation

Diagrams​

Diagrams

More Useful Stuff​

Front Matter & Metadata​

To add metadata to an MDX or Markdown file in Docusaurus, you use front matter, which is a YAML header placed at the top of the file. Here's how you can add front matter to your file​​:

---
id: page-id  # Unique identifier used for stable links, certain characters not allowed e.g. /
title: My Document Title
description: A brief description of my document
---

Each key-value pair in the front matter defines a piece of metadata. The id is particularly important as it can be used to create stable links to the document, as mentioned earlier. The front matter is parsed by Docusaurus to enrich the metadata for the document.

Linking to Other Notes (Markdown Files)​

To create a stable link to another Markdown file, you should use the file's ID. Here's how you can do it:

At the top of the Markdown file you want to link to, define an ID using the id front matter.

id: some-example-id

When linking to this file from another document, use the id instead of the file path:

[link text](example)

Using the ID ensures that even if you rename the file, the link remains intact as long as the id in the front matter stays the same.

To link to a specific section:

[Link Text](doc-id#section-id)

section-id is the ID of the specific section or header within the document. This is automatically generated from the header text by converting it to lowercase and replacing spaces with hyphens. For example, a section with the header ## My Section would have the ID my-section

MDX Validation​

To validate MDX files in a Docusaurus app, use the following methods:

  • MDX Playground: Debug compilation errors and validate syntax using the MDX playground.
  • VS Code Extension: Install the MDX extension for language support from the Visual Studio Marketplace.
  • ESLint Integration: Enable eslint-plugin-mdx for linting .mdx or .md files with ESLint. More details can be found on the eslint-plugin-mdx GitHub page.
  • Remark-Lint Plugins: Use remark-lint plugins alongside eslint-plugin-mdx to lint Markdown syntax. Configuration is read automatically, but use .eslintignore instead of .remarkignore. Refer to the remark-lint GitHub page for more information.