/web-meta-framework-docusaurus

name: web-meta-framework-docusaurus
description: Docusaurus 3.x documentation framework — site configuration, docs/blog plugins, sidebars, versioning, MDX, swizzling, and deployment

Docusaurus Patterns

> **Quick Guide:** Docusaurus 3.x is a React-powered static site generator for documentation. Everything > is configured in `docusaurus.config.js` (ESM), and `@docusaurus/preset-classic` bundles docs, blog, > pages, sitemap and theme in one entry. Sidebars are autogenerated from the filesystem, ordered by > `sidebar_position` front matter and `_category_.json`. Theme components are customised by swizzling. > Content is MDX v3, which is stricter than Markdown. `docusaurus docs:version` snapshots the whole > `docs/` tree, and > `docusaurus build` emits a static `build/` directory.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — full config, autogenerated and manual sidebars, multi-instance docs, docs-only mode, custom pages, navbar item types
• [examples/content.md](examples/content.md) — MDX strictness, admonitions, tabs, code blocks, assets, blog plugin and authors, remark/rehype, doc links
• [examples/customization.md](examples/customization.md) — swizzle safety, Infima CSS variables, versioning, i18n, search, deployment, Mermaid
• [reference.md](reference.md) — CLI commands, front matter fields, plugin and theme option tables, import aliases

---

<critical_requirements>

Before writing Docusaurus code

**Keep all site configuration in `docusaurus.config.js` (or `.ts`).** It is the single entry point the build reads, and config split across files has no mechanism to be merged.

**Start from `@docusaurus/preset-classic`.** It wires docs, blog, pages, sitemap and the theme together; decompose into individual plugins only when you need something the preset cannot express, such as a second docs instance.

**Swizzle with `--wrap` unless the change genuinely needs the component's internals.** A wrapped component keeps receiving upstream fixes; an ejected one is a snapshot you now own.

**Order autogenerated sidebars with `sidebar_position` front matter and `_category_.json`.** The filesystem drives routing and sidebar structure, so ordering stays next to the content it orders.

**Give each doc set its own plugin instance when it needs its own versioning.** One instance holding both versioned and unversioned docs has no way to keep them apart.

</critical_requirements>

---

**Auto-detection:** Docusaurus, docusaurus.config.js, docusaurus.config.ts, @docusaurus/preset-classic, @docusaurus/core, sidebars.js, docs:version, docusaurus build, docusaurus start, docusaurus deploy, docusaurus swizzle, MDX, _category_.json, sidebar_position, @site, @theme, @theme-original, plugin-content-docs, plugin-content-blog

**Applies to:**

• `docusaurus.config.js` — site metadata, presets, plugins, `themeConfig`, navbar, footer
• Sidebars: autogenerated, manual, multiple, and custom item generators
• Docs versioning and version banners
• Theme customization via swizzling and Infima CSS variables
• MDX content: admonitions, tabs, code block features, assets, heading anchors
• Custom pages in `src/pages/`, in React or MDX
• Blog plugin configuration and `authors.yml`
• Search wiring, i18n, and deploying the static build

**Handled elsewhere:**

• React component authoring itself — this skill covers the Docusaurus APIs a page or swizzled component calls, not the component model underneath.
• Request-time behaviour — `docusaurus build` emits static files, so anything needing a server at request time lives outside the site.
• Content sourced from a CMS or database — the plugins read files from disk at build time.
• The visual language beyond the Infima variables the theme exposes — those variables are the seam, and what you set them to is a design decision.
• The prose itself — this skill settles how a doc is wired into the site, not what it says.

---

<philosophy>

Docusaurus is an **opinionated documentation framework that trades flexibility for convention**. It decides routing (filesystem), content format (MDX) and structure (docs, blog, pages) so the work left is writing.

1. **Convention over configuration** — the filesystem drives routing and sidebar generation. Fighting it is fighting the framework. 2. **Preset first** — `preset-classic` is the common plugin set already wired together; individual plugins are for setups it cannot express. 3. **Content is data** — front matter is the metadata layer. `sidebar_position`, `slug`, `tags` and `custom_edit_url` live in the document rather than in a separate index. 4. **Swizzle rather than fork** — wrapping preserves upstream compatibility; ejecting produces a snapshot with your name on it. 5. **Static output** — there is no server runtime, no request-time rendering and no API routes.

</philosophy>

---

<decision_framework>

**Which sidebar strategy?** Autogenerated, ordered by `sidebar_position` and `_category_.json`, is right for almost everything — including large sites, as long as the sections map onto directories. A manual sidebar in `sidebars.js` earns its maintenance only when the navigation has to group documents the filesystem keeps apart, and the choice is not all-or-nothing: one sidebar array can hold an `autogenerated` item alongside hand-written entries. Independent doc sets (an API reference beside a guide) want separate plugin instances, each with its own sidebar, rather than either strategy stretched.

**Wrap, eject, or neither?** Adding content around a component is `--wrap`. Changing colours or spacing is neither — set the Infima CSS variables in `custom.css`. Changing internal logic means checking the component's safety level first: "Safe" makes ejecting acceptable, "Unsafe" means wrap or find another route, and "Forbidden" means the component is not swizzlable at all.

**Which content format?** A documentation article or blog post is `.md` or `.mdx` in `docs/` or `blog/`. A standalone page that is mo