235 lines
12 KiB
Markdown
235 lines
12 KiB
Markdown
---
|
|
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.
|