8.8 KiB
name, description, license, metadata, compatibility
| name | description | license | metadata | compatibility | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| documentation-docusaurus | Opinionated guidance for building and restructuring Docusaurus documentation sites on the Diátaxis framework — separating tutorials, how-to guides, reference, and explanation, and refusing to mix them on one page. Use when creating a new docs site or page, reorganising an existing one, deciding which quadrant a page belongs to, writing frontmatter, sidebars, or admonitions, editing docusaurus.config.ts, applying voice and inclusive-language standards, or setting up deployment to Vercel, Netlify, GitHub Pages, or Cloudflare Pages. Triggers on docs/, blog/, docusaurus.config, sidebars.ts, .mdx files, or any request to write, improve, build a local YAML data database for React/MDX views, render editable Draw.io sources with docusaurus-plugin-drawio, or restructure documentation — even when the user only says "write docs", "document this", or "the docs are a mess". Asks who the reader is and what they should be able to DO before writing, because the answer decides the structure. | MIT |
|
Designed for Docusaurus v3. Works with Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments |
Docusaurus Documentation Skill
Opinionated guidance for building documentation people actually read.
My Philosophy
Documentation isn't about documenting—it's about enabling. Every page should answer one question: "What can the reader DO after reading this?"
I follow the Diátaxis framework. Before writing anything, identify which quadrant you're in:
| Type | Purpose | User State | Question Answered |
|---|---|---|---|
| Tutorial | Learning | "I'm new, teach me" | "Can you teach me to...?" |
| How-to | Doing | "I need to accomplish X" | "How do I...?" |
| Reference | Information | "I need to look up Y" | "What is the API for...?" |
| Explanation | Understanding | "I want to understand why" | "Why does...?" |
Don't mix them. A tutorial that becomes reference midway loses both audiences.
Before You Write: Questions I'll Ask
When you ask me to create documentation, I need to understand:
- Who is reading this? (New user? Developer? API consumer? Decision maker?)
- What should they be able to DO after? (Not "know"—DO)
- Which Diátaxis quadrant? (Tutorial/How-to/Reference/Explanation)
- What do they already know? (Prerequisites matter)
If you haven't thought through these, I'll ask. Good docs require clear thinking first.
Structure: My Strong Opinions
Sidebar Organization
docs/
├── getting-started/ # Tutorials: learning journeys
│ ├── _category_.json # collapsed: false
│ └── ...
├── guides/ # How-tos: task completion
├── concepts/ # Explanation: understanding
├── reference/ # Reference: lookup
│ ├── api/
│ └── configuration/
└── resources/ # Links, community, changelog
Why this order? It matches the reader's journey: Learn → Do → Understand → Look up.
Frontmatter: Non-Negotiables
Every doc needs these. No exceptions:
---
title: "Action-Oriented Title" # What they'll DO, not what it IS
description: "One sentence outcome" # Appears in search, make it count
---
Skip sidebar_position unless order matters semantically. Let alphabetical work.
Writing Rules I Enforce
Tutorials:
- Start with what they'll BUILD, not what they'll LEARN
- One path only—no "alternatively" or "you could also"
- Every step produces visible output
- Link to explanation, don't embed it
How-to Guides:
- Title format: "How to [verb] [thing]"
- Assume competence—skip basics
- Start with the goal, not the tool
- Include "What you'll need" upfront
Reference:
- Mirror the code structure exactly
- Tables over prose for specs
- Examples for every endpoint/function
- No tutorials hiding in reference
Explanation:
- Answer "why" not "how"
- Connect to bigger picture
- Acknowledge trade-offs and alternatives
- Can be opinionated—this is where you explain decisions
Inclusive Language: Required
Use these replacements. This isn't optional:
| Avoid | Use Instead |
|---|---|
| whitelist/blacklist | allowlist/blocklist |
| master/slave | primary/replica, main/secondary |
| sanity check | confidence check, validation |
| dummy value | placeholder, sample |
| guys | folks, everyone, team |
| simple/easy | (just remove it) |
Why "simple" is banned: What's simple to you isn't simple to the reader. Saying "simply run X" makes struggling readers feel dumb.
Pronouns: Use "you" for the reader. Use "they" for hypothetical users. Avoid "we" unless it's genuinely collaborative.
Dynamic Documentation Patterns
Local YAML data-backed documentation
When Epics, Features, Tasks, requirements, or architectural decisions must feed several documentation views, keep the authoritative records in a local .yml-only data tree and load them during the Docusaurus build. Requirements must use separate functional and non-functional folders, and architectural decisions must use the exact data/architecture-decisions/ folder. Do not duplicate records inside MDX. Follow references/local-yaml-data-database.md for record schemas, stable IDs, canonical relationships, generated indexes, validation, React hooks/components, MDX composition, and maintenance commands.
Draw.io source diagrams
When a page needs a Draw.io diagram, keep the editable .drawio XML in the documentation repository and render that source directly with docusaurus-plugin-drawio. Load drawio-main to author or change the diagram, then follow references/drawio-source-diagrams.md to install the plugin with pnpm, register it, consume the source from MDX with @theme/Drawio and !!raw-loader!, select multi-page diagrams, and verify the production build and browser rendering. An exported PNG/SVG alone is not an onboarded source diagram.
Interactive Elements (Use Sparingly)
Tabs for platform differences:
<Tabs groupId="os">
<TabItem value="mac" label="macOS" default>
Details for optional deep-dives:
<details>
<summary>Why does this matter?</summary>
...explanation that most readers can skip...
</details>
Don't use tabs for: Code language alternatives (pick one and show it well), or "beginner vs advanced" (separate pages instead).
Admonitions: The Hierarchy
:::tip → "This will make your life easier"
:::note → "Relevant context you might miss"
:::warning → "This could cause problems"
:::danger → "This WILL break things if ignored"
One admonition per section max. If everything is highlighted, nothing is.
What I Won't Do
- Create docs without understanding the audience
- Mix documentation types in one page
- Add "simple" or "easy" to instructions
- Generate walls of code without context
- Skip frontmatter description fields
- Create sidebars deeper than 3 levels
Reference Files
Load the one that matches the task. Don't read all four.
| You're about to | Read |
|---|---|
| Write a page, or decide which quadrant it belongs in | references/diataxis-patterns.md — copy-ready template per quadrant, the decision tree, and how to link between them |
| Write or edit prose, headings, lists, or code examples | references/writing-guide.md — voice, words to cut, inclusive language, pre-publish checklist |
Touch docusaurus.config.ts |
references/config-reference.md — the options that matter, sensible defaults, config anti-patterns |
| Build or maintain a local YAML database that feeds React components and MDX | references/local-yaml-data-database.md — dedicated entity folders, .yml schemas, indexes, relationships, build-time loading, typed hooks, and validation |
Onboard or render an editable .drawio source |
references/drawio-source-diagrams.md — pnpm install, plugin registration, MDX raw-source import, viewer options, and verification |
| Ship the site, or debug a failing build | references/deployment.md — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |
Getting Started
Tell me:
- What documentation you're building
- Who it's for
- What they should be able to do after
I'll ask follow-up questions, then we'll build something people actually want to read.