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:
docs/build/Before you begin, make sure that you have the following tools:
To check your Node.js version:
node --version
Use the Docusaurus initializer to create a site from the classic preset.
npx create-docusaurus@latest my-docs-site classic
cd my-docs-site
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 |
| Markdown and MDX documentation pages |
| Custom React pages, such as landing pages |
| Static assets, such as images |
The following files control site settings and navigation:
File | Purpose |
| Site title, URL, plugins, and theme options |
| Docs sidebar navigation |
| Global style overrides |
To see how the generated site connects docs content to navigation:
docusaurus.config.ts and review the docs preset option that points to ./sidebars.ts.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.
docs/getting-started.md.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.
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.
sidebars.ts and make sure that the tutorial sidebar includes getting-started.The file should match the following example:import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
tutorialSidebar: [
'intro',
'getting-started',
],
};
export default sidebars;
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.
npm start
Docusaurus opens http://localhost:3000 in your browser. You should see:
//docs/intro and /docs/getting-startedsidebars.tsTo verify hot reload:
When you are ready to publish the site, create a production build.
npm run buildDocusaurus writes the output to the
build/ directory.npm run serve
You can deploy the contents of build/ to any static host.
Common static hosts include the following services:
To deploy manually:
build/ to your static host.For GitHub Pages, Docusaurus also provides a deploy script.
docusaurus.config.ts, set url and baseUrl to match your hosting target.npm run deploy
You now have a working Docusaurus documentation site. What to do next:
docs/ and expand sidebars.ts.docusaurus.config.ts and src/css/custom.css.main publish automatically.