documentation-docusaurus-3darch/SKILL.md

---
name: documentation-docusaurus
description: >
  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.
license: MIT
metadata:
  author: workspace-skills-code-agent
  version: "1.2"
  spec: agentskills.io/specification
  framework: Diátaxis
  hermes:
    tags: [docusaurus, documentation, diataxis, drawio, mdx]
    related_skills: [drawio-main]
compatibility: 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:

1. **Who is reading this?** (New user? Developer? API consumer? Decision maker?)
2. **What should they be able to DO after?** (Not "know"—DO)
3. **Which Diátaxis quadrant?** (Tutorial/How-to/Reference/Explanation)
4. **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:
```yaml
---
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](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](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:
```mdx
<Tabs groupId="os">
  <TabItem value="mac" label="macOS" default>
```

Details for optional deep-dives:
```mdx
<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](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](references/writing-guide.md) — voice, words to cut, inclusive language, pre-publish checklist |
| Touch `docusaurus.config.ts` | [references/config-reference.md](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](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](references/drawio-source-diagrams.md) — pnpm install, plugin registration, MDX raw-source import, viewer options, and verification |
| Repair a docs section that builds but violates a required hierarchy or content contract | [references/architecture-ia-remediation.md](references/architecture-ia-remediation.md) — RED-first structure validation, approval-safe scaffolding, link pitfalls, browser checks, and remote PR/CI readback |
| Ship the site, or debug a failing build | [references/deployment.md](references/deployment.md) — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |

## Package-manager validation pitfall

If `pnpm` is available only through `corepack`, `corepack pnpm validate` can still fail when the `validate` script invokes nested `pnpm` commands, because child scripts resolve `pnpm` from `PATH`. Before treating this as a repository failure, either:

- add a trusted `pnpm` shim that executes `corepack pnpm "$@"` to `PATH`; or
- run each validation script directly through `corepack pnpm`.

Re-run the complete validator and production build after fixing command resolution. Do not report a successful build from the outer command alone.

## Getting Started

Tell me:
1. What documentation you're building
2. Who it's for
3. What they should be able to do after

I'll ask follow-up questions, then we'll build something people actually want to read.