Quick Guide: Docusaurus 3.x is a React-powered static site generator for documentation. Configure everything in

docusaurus.config.js

(ESM). Use

@docusaurus/preset-classic

for docs + blog + pages + sitemap in one preset. Sidebars can be fully autogenerated from filesystem structure using

_category_.json

and front matter

sidebar_position

. Customize theme components via swizzling (prefer

--wrap

over

--eject

). MDX is the default content format — use front matter for metadata, admonitions for callouts, and import React components directly in

.mdx

files. Version docs with

docusaurus docs:version

. Deploy the

build/

output to any static host.

All code must follow project conventions in CLAUDE.md

docusaurus.config.js

.ts

@docusaurus/preset-classic

--wrap

--eject

sidebar_position

_category_.json

• Configuring

  docusaurus.config.js

  (site metadata, presets, plugins, theme, navbar, footer)
• Setting up or modifying sidebar structure (autogenerated or manual)
• Adding versioned documentation
• Customizing theme components via swizzling
• Writing MDX content with Docusaurus-specific features (admonitions, tabs, code blocks)
• Creating custom pages with React components
• Configuring the blog plugin
• Setting up search (Algolia DocSearch or local)
• Deploying Docusaurus to static hosting
• Configuring i18n / localization

• General React component patterns (Docusaurus uses React internally but this skill covers Docusaurus APIs, not React fundamentals)
• CSS/styling approaches not specific to Docusaurus theming (general CSS patterns are a separate concern)
• Git hooks, linting, or formatting setup (separate from documentation framework concerns)
• Content that belongs in the docs themselves, not the site framework
• VitePress — Vue-based, different config format and plugin system
• Nextra — Next.js-based, uses

  _meta.json

  not

  _category_.json

  , different routing model
• Starlight — Astro-based, uses

  astro.config.mjs

  and content collections, different architecture entirely

• Core Configuration & Sidebars — docusaurus.config.js, preset-classic, sidebars, front matter, custom pages
• MDX & Content — MDX features, admonitions, tabs, code blocks, assets, blog plugin
• Customization & Deployment — Swizzling, CSS variables, versioning, i18n, search, deployment

• Quick Reference — CLI commands, front matter fields, config option tables

1. Convention over configuration — filesystem structure drives routing and sidebar generation; fight this and you fight the framework
2. Preset-first —

   preset-classic

   bundles the common plugin set; only decompose into individual plugins when you need multiple docs instances or unusual setups
3. Content as data — front matter is the metadata layer;

   sidebar_position

   ,

   slug

   ,

   tags

   ,

   custom_edit_url

   all live in the document, not in external config
4. Swizzle, don't fork — customize theme components via the swizzle CLI; wrapping preserves upstream compatibility, ejecting creates a snapshot you must maintain
5. Static output —

   docusaurus build

   produces a static site; there is no server runtime, no SSR in production, no API routes

export default

// docusaurus.config.js — minimal production setup
export default {
  title: "My Docs",
  tagline: "Documentation for My Project",
  url: "https://docs.example.com",
  baseUrl: "/",
  onBrokenLinks: "throw",
  onBrokenMarkdownLinks: "throw",
  favicon: "img/favicon.ico",

  presets: [
    [
      "@docusaurus/preset-classic",
      {
        docs: {
          sidebarPath: "./sidebars.js",
          editUrl: "https://github.com/my-org/my-repo/edit/main/docs-site/",
          showLastUpdateTime: true,
        },
        blog: { showReadingTime: true },
        theme: { customCss: ["./src/css/custom.css"] },
      },
    ],
  ],

  themeConfig: {
    navbar: {
      title: "My Docs",
      items: [
        /* nav items */
      ],
    },
    footer: {
      style: "dark",
      links: [
        /* footer columns */
      ],
    },
    docs: { sidebar: { hideable: true, autoCollapseCategories: true } },
  },
};

onBrokenLinks: 'throw'

Full example: See examples/core.md for complete config with navbar, footer, and multi-instance docs setup.

// sidebars.js — autogenerated (recommended)
export default {
  docs: [{ type: "autogenerated", dirName: "." }],
};

_category_.json

---
sidebar_position: 3
sidebar_label: Quick Start
---

// docs/guides/_category_.json
{
  "label": "Guides",
  "position": 2,
  "collapsible": true,
  "collapsed": false,
  "link": { "type": "generated-index", "title": "All Guides" }
}

sidebar_position

01-intro.md

Full example: See examples/core.md for manual sidebars, custom sidebar items generator, and multi-sidebar setups.

```jsx
// src/theme/Footer/index.js — wrapping example
import React from "react";
import Footer from "@theme-original/Footer";

export default function FooterWrapper(props) {
  return (
    <>
      <Footer {...props} />
      <div className="custom-banner">Custom content below footer</div>
    </>
  );
}

@theme-original/

@theme/

@theme/Footer

Full example: See examples/customization.md for swizzling safety levels, common swizzle targets, and CSS variable theming.

---
title: My Document
description: SEO description for this page
sidebar_position: 1
tags: [getting-started, tutorial]
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

:::tip[Pro Tip]
Admonitions support `note`, `tip`, `info`, `warning`, `danger` types.
The bracket syntax `:::tip[Custom Title]` sets the title.
:::

<Tabs>
  <TabItem value="npm" label="npm" default>
    ```bash npm install my-package ```
  </TabItem>
  <TabItem value="yarn" label="yarn">
    ```bash yarn add my-package ```
  </TabItem>
</Tabs>

{

<

\{

\<

Full example: See examples/content.md for code block features, asset handling, and blog plugin configuration.

This creates `versioned_docs/version-1.0.0/` and `versioned_sidebars/version-1.0.0-sidebars.json`. Configure version behavior in the docs plugin:

```javascript
// In preset-classic docs options
docs: {
  lastVersion: 'current',
  versions: {
    current: { label: '2.0.0-beta', path: 'next', banner: 'unreleased' },
    '1.0.0': { label: '1.0.0', path: '1.0.0', banner: 'none' },
  },
  onlyIncludeVersions: ['current', '1.0.0'],
}

onlyIncludeVersions

Full example: See examples/customization.md for version banner configuration and multi-version navigation.

• Using

  onBrokenLinks: 'ignore'

  or

  'log'

  in production — broken links should fail the build (

  'throw'

  )
• Ejecting theme components when wrapping would suffice — ejected components miss upstream bug fixes and feature additions
• Using

  @theme/ComponentName

  import in a swizzle wrapper instead of

  @theme-original/ComponentName

  — creates an infinite import loop
• Putting all sidebar config in

  sidebars.js

  manually when autogenerated would work — creates a maintenance burden that falls out of sync with actual docs

• Versioning every release instead of only when docs content actually changes — bloats build time and output size
• Not setting

  onBrokenMarkdownLinks: 'warn'

  at minimum — silent broken links accumulate
• Missing

  editUrl

  in docs plugin config — blocks "Edit this page" links that drive community contributions
• Not using

  showLastUpdateTime: true

  — readers cannot tell how current a doc page is

• Bare

  {

  or

  <

  in MDX content causing build failures — escape with

  \{

  and

  \<

  or wrap in code fences
• Forgetting to restart the dev server after changing

  docusaurus.config.js

  — config changes are not hot-reloaded
• Using

  .md

  extension with JSX when

  format: 'detect'

  is configured — in detect mode, only

  .mdx

  files support JSX (default mode processes both)
• Creating

  _category_.json

  with wrong field names (

  name

  instead of

  label

  ,

  order

  instead of

  position

  )
• Importing from

  @docusaurus/

  packages directly in MDX — use

  @theme/

  or

  @site/

  aliases instead

• baseUrl

  must end with

  /

  — omitting the trailing slash breaks asset resolution
• Static assets in

  static/

  are served from root, not from

  baseUrl

  — use

  require()

  or

  useBaseUrl()

  for path-safe references
• Blog authors are configured in

  blog/authors.yml

  , not in

  docusaurus.config.js

• The

  slug

  front matter field overrides the URL path derived from the filename — useful for keeping clean URLs when renaming files

• docs-only mode

  requires setting

  routeBasePath: '/'

  in the docs plugin AND

  blog: false

  in the preset
• Custom pages in

  src/pages/

  use the file path as the route —

  src/pages/support.tsx

  becomes

  /support

• Tabs component state is not shared between instances by default — use

  groupId

  prop to sync tab selection across the page

All code must follow project conventions in CLAUDE.md

docusaurus.config.js

@docusaurus/preset-classic

--wrap

--eject

sidebar_position

_category_.json