corp-v1-3darch-skills-code-agent/documentation-docusaurus-3darch
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
refactor/diagrams-drawio-reference
documentation-docusaurus-3d…/SKILL.md
T

12 KiB
Raw Permalink Blame History

name, description, license, metadata, compatibility
name description license metadata compatibility
documentation-docusaurus--3darch 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. 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
diagrams-drawio
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).

Project engineering peers:

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

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.

Reference in New Issue View Git Blame Copy Permalink