# documentation-docusaurus

Agent Skill for building documentation sites with **Docusaurus**, structured on the
[Diátaxis](https://diataxis.fr/) framework — tutorials, how-to guides, reference, and
explanation kept strictly apart.

Opinionated by design. It takes positions on structure, voice, and configuration rather than
listing options, and it asks who the reader is and what they should be able to *do* before
writing anything.

## Layout

```text
documentation-docusaurus/
├── SKILL.md                          # Entry point — Diátaxis quadrants, structure, voice rules
└── references/
    ├── diataxis-patterns.md          # Template per quadrant, decision tree, cross-linking
    ├── writing-guide.md              # Voice, words to cut, inclusive language, checklist
    ├── config-reference.md           # docusaurus.config.ts — what matters, what to leave alone
    └── deployment.md                 # Vercel, Netlify, GitHub Pages, Cloudflare, debugging
```

## The core idea

| Type | Purpose | Question it answers |
|---|---|---|
| **Tutorial** | Learning | "Can you teach me to…?" |
| **How-to** | Doing | "How do I…?" |
| **Reference** | Information | "What is the API for…?" |
| **Explanation** | Understanding | "Why does…?" |

Don't mix them. A tutorial that turns into reference halfway through loses both audiences.

The docs tree follows the reader's journey — learn, do, understand, look up:

```text
docs/
├── getting-started/     # Tutorials
├── guides/              # How-tos
├── concepts/            # Explanation
├── reference/           # Reference
└── resources/           # Links, community, changelog
```

## Deploy

```bash
cd ../skill-manager/scripts
task deploy -- --skill-dir="$(cd ../../documentation-docusaurus && pwd)"
```

Built with the `skill-manager` skill, following the
[agentskills.io specification](https://agentskills.io/specification).