55 lines
2.0 KiB
Markdown
55 lines
2.0 KiB
Markdown
# 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
|
|
└── drawio-source-diagrams.md # Editable Draw.io source rendering in Docusaurus MDX
|
|
```
|
|
|
|
## 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).
|