documentation-docusaurus/SKILL.md

name, description, license, metadata, compatibility

name	description	license	metadata	compatibility
documentation-docusaurus	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.	MIT	author version spec framework hermes workspace-skills-code-agent 2.0 agentskills.io/specification Diátaxis tags related_skills docusaurus documentation diataxis drawio mdx react-flow gitea ci-cd pages diagrams-drawio gitea-repository-operations	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.

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

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

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

The reusable Gitea Actions starter is 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.