documentation-docusaurus-3darch/SKILL.md

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, create React Flow roadmaps or dependency maps, 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	author version spec framework hermes workspace-skills-code-agent 1.3 agentskills.io/specification Diátaxis tags related_skills docusaurus documentation diataxis drawio mdx react-flow drawio-main	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:

---
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.

React Flow roadmaps and dependency maps

Use @xyflow/react when validated documentation data needs an interactive roadmap, Gantt-like timeline, Feature dependency graph, Requirement-to-Feature traceability map, or architectural decision-to-Feature map. React Flow is the renderer, not the source database or an automatic layout engine. Follow references/react-flow-visualizations.md for Docusaurus BrowserOnly integration, deterministic Gantt positioning, Dagre/ELK layout choices, source-YAML adapters, read-only interaction, accessibility, sharp styling, semantic table fallbacks, testing, and browser verification.

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
Build a React Flow roadmap, Gantt-like view, or dependency/traceability map	references/react-flow-visualizations.md — @xyflow/react, Docusaurus client boundaries, YAML adapters, layouts, accessibility, fallbacks, and verification
Onboard or render an editable .drawio source	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 — 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 — 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.