---
name: documentation-docusaurus--3darch
description: >
  Opinionated Docusaurus v3 guidance using Diátaxis. Use when creating or restructuring documentation,
  writing MDX, configuring navigation or deployment, building a local YAML data database, creating
  React Flow roadmaps and dependency maps, or rendering editable Draw.io sources. Triggers on docs/,
  blog/, docusaurus.config, sidebars, MDX, documentation data, and requests to write or improve docs.
  Requires the intended reader and outcome before writing, keeps documentation types separate, and
  applies accessibility, inclusive-language, build, browser, and deployment verification standards.
license: MIT
metadata:
  author: workspace-skills-code-agent
  version: "1.3"
  spec: agentskills.io/specification
  framework: Diátaxis
  hermes:
    tags: [docusaurus, documentation, diataxis, drawio, mdx, react-flow]
    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

## 3D Architecture Wizzard Project Adoption

This is the primary project-adopted skill for **3D Architecture Wizzard** (`3darch`).

- Central source: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/documentation-docusaurus
- Source branch: `test`
- Source commit: `f810f8c92005e5d55b08700b67fd34a37be435bc`
- Adopted repository: https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/documentation-docusaurus--3darch
- Application: https://gitea.lego-cloud.eu/corp-v1-3darch/corp-v1-3darch
- Documentation: https://gitea.lego-cloud.eu/corp-v1-3darch/corp-v1-3darch-documentation
- Environment namespace: `CORP_V1_3DARCH_*`
- Global diagram skill: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/drawio-main
- Global glossary skill: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1--glossary
- Project automation: none; no scheduler job is authorized.

Project engineering peers:
- `development-branching-strategy--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-branching-strategy--3darch
- `development-gitops-argo-cd--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-gitops-argo-cd--3darch
- `development-monorepo-pnpm--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-monorepo-pnpm--3darch
- `development-scripts--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-scripts--3darch
- `devsecops-ci-cd-gitea--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/devsecops-ci-cd-gitea--3darch
- `documentation-docusaurus--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/documentation-docusaurus--3darch
- `template-engine-copier--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/template-engine-copier--3darch


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

### 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](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](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 |
| Build a React Flow roadmap, Gantt-like view, or dependency/traceability map | [references/react-flow-visualizations.md](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](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.