documentation-docusaurus/SKILL.md

---
name: documentation-docusaurus
description: >
  Opinionated Docusaurus v3 guidance using Diátaxis. Use when creating or restructuring documentation,
  writing MDX, configuring navigation or deployment, building evidence registries and local YAML data,
  creating React Flow or Draw.io visualizations, provisioning Gitea repositories, or publishing through
  self-hosted Gitea Actions and LEGO Cloud Pages. Triggers on docs/, blog/, docusaurus.config, sidebars,
  MDX, documentation data, Gitea documentation repositories, CI/CD, and documentation delivery.
  Requires audience and outcome clarity, separates documentation types, preserves canonical evidence,
  and applies accessibility, build, browser, exact-SHA CI, remote-readback, and deployment verification.
license: MIT
metadata:
  author: workspace-skills-code-agent
  version: "2.0"
  spec: agentskills.io/specification
  framework: Diátaxis
  hermes:
    tags: [docusaurus, documentation, diataxis, drawio, mdx, react-flow, gitea, ci-cd, pages]
    related_skills: [diagrams-drawio, gitea-repository-operations]
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.*

## Authoritative repository

This VSSA-managed skill is maintained in Gitea at
`https://gitea.lego-cloud.eu/vssa-v1-skills-code-agent/documentation-docusaurus`.
Treat repository `main` as the source of truth. The maintainer worktree is
`/opt/data/documentation-docusaurus-skill`, and the runtime installation is a symlink to that
worktree. For every reusable improvement: fetch and fast-forward, edit the repository package,
run `python3 scripts/validate_skill.py`, review the complete diff, commit and push, verify exact ref
equality and authenticated remote readback, require the exact-SHA Gitea Actions task to succeed, and
then verify `skill_view(name='documentation-docusaurus')` loads the changed package. Never maintain a
divergent runtime-only copy.

This repository is an independent VSSA adoption. Upstream or project-specific skill repositories are
read-only learning sources: compare deliberately and port only generally useful, verified practices.
Never push to or rewrite another project's skill repository while maintaining this one. See
[`PROVENANCE.md`](PROVENANCE.md).

## Capability router

Use this single skill for the full documentation lifecycle:

| Work | Primary guidance |
|---|---|
| Audience, page purpose, prose and information architecture | This file plus Diátaxis and writing references |
| Docusaurus configuration, MDX, React Flow and Draw.io | Configuration and visualization references |
| Existing Markdown/evidence corpus migration | Corpus, registry, cross-linking and multi-section references |
| Gitea organization/repository provisioning and Git delivery | [`references/gitea-docusaurus-delivery.md`](references/gitea-docusaurus-delivery.md) plus `gitea-repository-operations` |
| Gitea Actions and LEGO Cloud Pages publication | Delivery, behavioral acceptance and deployment references |

Load `gitea-repository-operations` alongside this skill for repository/API/SSH mutations. This skill
defines documentation-specific structure, migration, CI/CD and acceptance requirements; the repository
operations skill remains authoritative for general Gitea safety, authentication and remote verification.

## 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 `diagrams-drawio` 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 |

### Gitea, evidence-portal and publication references

| You're about to | Read |
|---|---|
| Provision or publish a Docusaurus repository on Gitea/LEGO Cloud Pages | [references/gitea-docusaurus-delivery.md](references/gitea-docusaurus-delivery.md) — merged repository, pnpm, Actions, Pages and verification workflow |
| Preserve an established Markdown/evidence corpus during Docusaurus adoption | [references/migrating-existing-markdown-corpora.md](references/migrating-existing-markdown-corpora.md) |
| Build a dedicated homepage and fully local search | [references/dedicated-homepage-local-search.md](references/dedicated-homepage-local-search.md) |
| Generate a conservative cross-client system/provider registry | [references/generated-evidence-registries.md](references/generated-evidence-registries.md) |
| Organize a large evidence portal around user tasks | [references/research-led-evidence-registry-ia.md](references/research-led-evidence-registry-ia.md) |
| Split Clients, Systems, Contractors or other major collections into dedicated sidebars | [references/multi-section-evidence-portals.md](references/multi-section-evidence-portals.md) |
| Link source observations to generated system/contractor dossiers | [references/cross-linking-source-and-derived-dossiers.md](references/cross-linking-source-and-derived-dossiers.md) |
| Prove interactive behavior rather than only a green build | [references/behavioral-acceptance-for-doc-portals.md](references/behavioral-acceptance-for-doc-portals.md) |
| Adapt a selected reference design without copying it | [references/reference-inspired-documentation-portals.md](references/reference-inspired-documentation-portals.md) |
| Use C4 Mermaid or the maintained modern theme | [references/c4-docusaurus.md](references/c4-docusaurus.md) and [references/modern-docusaurus-theme.md](references/modern-docusaurus-theme.md) |
| Start a source-backed research/address-book repository | [references/research-address-book-repositories.md](references/research-address-book-repositories.md) |

The reusable Gitea Actions starter is
[`templates/gitea-actions-build.yml`](templates/gitea-actions-build.yml). Treat it as a starting point,
then adapt it to the repository's actual package manager, validators, route base, Pages destination and
self-hosted runner constraints.

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

## Gitea delivery gate

A local build is not a delivered documentation change. For Gitea-backed sites, completion requires:

1. discovery and synchronization before mutation;
2. project validators, production build and `git diff --check`;
3. reviewed commit and push through explicit non-interactive SSH identity;
4. local/remote ref equality and authenticated readback of a distinctive source marker;
5. the latest terminal Gitea Actions task matched to the exact pushed SHA, with every matching task in
   `success` state;
6. route-level and behavior-level verification of changed documentation; and
7. deployed content verification through the authorized Pages path or service proxy. An expected
   Keycloak/OAuth `302` proves the authentication boundary, not the changed page body.

Never treat a push, green build, visible control, HTTP status alone, or guessed static route as feature
acceptance. Map every requirement to direct evidence and preserve canonical source artifacts rather than
editing generated output.

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