Quick Start
A Docusaurus project is a Node package. Everything the site needs is a dependency, every page is a file under docs/ or src/pages/, and the build output is a folder of static assets that any host can serve. The quickest way to get a working site is to let the official scaffolder generate that skeleton, because it sets up the configuration file, the sidebars, the stylesheet override, and the npm scripts that the rest of this chapter refers to.
Run the scaffolder and pick the classic template:
npx create-docusaurus@latest my-site classic
cd my-site
npm install
npm start
The dev server starts and prints a local URL, normally on port 3000. You edit Markdown files and the browser updates without a manual refresh. When you are ready to check the production output, build the site and serve the result locally:
npm run build
npm run serve
The build command writes a build/ directory containing HTML, CSS, JavaScript, and copied static assets. The serve command serves that directory, which is the closest local approximation of what a static host will do — worth running before every deploy, because it surfaces broken links and missing images that the dev server can be lenient about.
The generated project looks like this:
my-site/
├── docusaurus.config.js # site config: plugins, themes, navbar, footer
├── sidebars.js # the documentation navigation tree
├── docs/ # documentation pages (.md / .mdx)
│ └── intro.md
├── blog/ # blog posts, named YYYY-MM-DD-slug.md
│ └── 2024-01-01-hello.md
├── src/
│ ├── css/custom.css # CSS variable overrides for the theme
│ ├── components/ # your own React components
│ ├── pages/ # standalone pages (React or .mdx)
│ └── theme/ # swizzled theme components, if any
├── static/ # files copied verbatim to the site root
├── package.json
└── README.md
Two of those files do most of the work. docusaurus.config.js describes the site — its title, its URL, the plugins that own each content folder, the theme options for the navbar and footer, and the search configuration. sidebars.js describes the documentation navigation as a tree of labels and document identifiers:
// sidebars.js
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
docs: [
'intro',
{
type: 'category',
label: 'Guides',
collapsed: false,
items: ['guides/getting-started', 'guides/deployment'],
},
{
type: 'autogenerated',
dirName: 'reference',
},
],
};
module.exports = sidebars;
The autogenerated entry is worth understanding early: instead of listing every file by hand, you point it at a directory and Docusaurus builds the sidebar from the sidebar_position frontmatter of the files it finds. That keeps the navigation correct as the reference section grows, and it is why the scaffolded sidebars.js uses it for the reference material.
A documentation page is a Markdown file whose frontmatter carries the metadata the sidebar and the page header need:
---
id: getting-started
title: Getting Started
sidebar_label: Start Here
sidebar_position: 1
tags: [setup]
---
# Getting Started
Install the package and run the development server:
```bash
npm install acme
npm run dev
```
The id is how other pages refer to this one — in pagination_next, in sidebars.js, and in cross-document links. The sidebar_position orders the page within its section. Together they let you reorganize a documentation set by moving files and editing numbers, without touching prose.
The npm scripts generated by the scaffolder cover the whole day-to-day loop:
| Script | What it does |
|---|---|
npm start | Start the development server with hot reload |
npm run build | Produce the production bundle in build/ |
npm run serve | Serve the built build/ directory locally |
npm run clear | Delete the cache so the next build starts cold |
npm run swizzle | Copy theme components into src/theme/ for local editing |
npm run write-translations | Extract translatable strings into i18n/ |
A few problems are common in the first hour and are usually easy to diagnose. If the dev server exits immediately, the usual cause is a Node version that the installed dependencies do not support; check the version printed in the error and switch with a version manager. If the build fails on a link, the message names the file and the target, and the fix is either to correct the path or to set the corresponding onBrokenLinks option in the configuration. If an image in static/ does not appear, remember that the static folder is copied to the site root, so the link is /img/logo.svg rather than a relative path. And if you change the structure of sidebars.js and nothing happens, run npm run clear — the sidebar is cached aggressively.
Once the dev server is running and you can see the scaffolded page, the project is genuinely started. The next thing to do is to model your own content: decide what belongs in docs/ versus blog/, fill in the navbar and footer in the configuration file, and set the site url and baseUrl to the real deployment address, because those two values feed the sitemap, the canonical links, and the social sharing metadata.
