Add documentation-docusaurus agent skill
Packages generic-documentation-v1 as documentation-docusaurus: Diataxis quadrants, structure and voice rules, and four references for patterns, writing, config, and deployment. Content preserved from the source; renames the skill, strengthens the description for triggering, and converts the reference list into a routing table stating when to load each file. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -1 +1,53 @@
|
||||
# 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).
|
||||
|
||||
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: documentation-docusaurus
|
||||
description: >
|
||||
Opinionated guidance for building and restructuring Docusaurus documentation sites on the
|
||||
Diátaxis framework — separating tutorials, how-to guides, reference, and explanation, and
|
||||
refusing to mix them on one page. Use when creating a new docs site or page, reorganising an
|
||||
existing one, deciding which quadrant a page belongs to, writing frontmatter, sidebars, or
|
||||
admonitions, editing docusaurus.config.ts, applying voice and inclusive-language standards,
|
||||
or setting up deployment to Vercel, Netlify, GitHub Pages, or Cloudflare Pages. Triggers on
|
||||
docs/, blog/, docusaurus.config, sidebars.ts, .mdx files, or any request to write, improve,
|
||||
or restructure documentation — even when the user only says "write docs", "document this",
|
||||
or "the docs are a mess". Asks who the reader is and what they should be able to DO before
|
||||
writing, because the answer decides the structure.
|
||||
license: MIT
|
||||
metadata:
|
||||
author: workspace-skills-code-agent
|
||||
version: "1.0"
|
||||
spec: agentskills.io/specification
|
||||
framework: Diátaxis
|
||||
compatibility: 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.*
|
||||
|
||||
## 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
|
||||
|
||||
### 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 |
|
||||
| Ship the site, or debug a failing build | [references/deployment.md](references/deployment.md) — Vercel, Netlify, GitHub Pages, Cloudflare, and common failures |
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,218 @@
|
||||
# Configuration Reference
|
||||
|
||||
Essential `docusaurus.config.ts` options. Not exhaustive—see [Docusaurus docs](https://docusaurus.io/docs/api/docusaurus-config) for everything.
|
||||
|
||||
---
|
||||
|
||||
## Minimum Viable Config
|
||||
|
||||
```typescript
|
||||
const config = {
|
||||
title: 'Project Name',
|
||||
url: 'https://docs.example.com',
|
||||
baseUrl: '/',
|
||||
|
||||
presets: [
|
||||
['classic', {
|
||||
docs: { routeBasePath: '/' }, // Docs at root
|
||||
blog: false, // Disable if not using
|
||||
theme: { customCss: './src/css/custom.css' },
|
||||
}],
|
||||
],
|
||||
};
|
||||
```
|
||||
|
||||
My opinion: Start minimal. Add complexity only when you need it.
|
||||
|
||||
---
|
||||
|
||||
## The Options That Actually Matter
|
||||
|
||||
### Site Identity
|
||||
|
||||
```typescript
|
||||
title: 'Your Project', // Browser tab, search results
|
||||
tagline: 'One sentence pitch', // Shows in default homepage
|
||||
favicon: 'img/favicon.ico',
|
||||
```
|
||||
|
||||
### URLs
|
||||
|
||||
```typescript
|
||||
url: 'https://docs.example.com', // Production URL (no trailing slash)
|
||||
baseUrl: '/', // Usually '/' unless in subdirectory
|
||||
trailingSlash: false, // Pick one and stick with it
|
||||
```
|
||||
|
||||
**Opinion:** `trailingSlash: false`. It's cleaner and most platforms handle it correctly.
|
||||
|
||||
### Build Behavior
|
||||
|
||||
```typescript
|
||||
onBrokenLinks: 'throw', // Fail build on broken links
|
||||
onBrokenMarkdownLinks: 'throw', // Same for markdown links
|
||||
```
|
||||
|
||||
**Opinion:** Always `throw` in production. `warn` during development is OK.
|
||||
|
||||
---
|
||||
|
||||
## Preset: Classic (Use This)
|
||||
|
||||
```typescript
|
||||
presets: [
|
||||
['classic', {
|
||||
docs: {
|
||||
sidebarPath: './sidebars.ts',
|
||||
routeBasePath: '/', // Docs as homepage
|
||||
editUrl: 'https://github.com/org/repo/edit/main/',
|
||||
showLastUpdateTime: true, // Shows git commit time
|
||||
},
|
||||
blog: {
|
||||
showReadingTime: true,
|
||||
blogSidebarCount: 'ALL',
|
||||
},
|
||||
theme: {
|
||||
customCss: './src/css/custom.css',
|
||||
},
|
||||
}],
|
||||
],
|
||||
```
|
||||
|
||||
### Docs-Only Mode
|
||||
|
||||
Set `routeBasePath: '/'` and either `blog: false` or keep blog at `/blog`.
|
||||
|
||||
---
|
||||
|
||||
## Theme Config: What Readers See
|
||||
|
||||
### Navbar
|
||||
|
||||
```typescript
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
title: 'Project',
|
||||
logo: { alt: 'Logo', src: 'img/logo.svg' },
|
||||
items: [
|
||||
{ type: 'docSidebar', sidebarId: 'docs', label: 'Docs' },
|
||||
{ to: '/blog', label: 'Blog' },
|
||||
{ href: 'https://github.com/...', label: 'GitHub', position: 'right' },
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**Opinion:** Keep navbar items under 5. More than that, use dropdowns.
|
||||
|
||||
### Color Mode
|
||||
|
||||
```typescript
|
||||
colorMode: {
|
||||
defaultMode: 'light', // Or 'dark'
|
||||
respectPrefersColorScheme: true, // Honor system preference
|
||||
},
|
||||
```
|
||||
|
||||
**Opinion:** Always `respectPrefersColorScheme: true`. Don't force your preference.
|
||||
|
||||
### Sidebar Behavior
|
||||
|
||||
```typescript
|
||||
docs: {
|
||||
sidebar: {
|
||||
hideable: true, // Let users collapse it
|
||||
autoCollapseCategories: true, // Only one category expanded
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
### Search (Algolia)
|
||||
|
||||
```typescript
|
||||
algolia: {
|
||||
appId: 'YOUR_APP_ID',
|
||||
apiKey: 'YOUR_SEARCH_API_KEY', // Public search-only key
|
||||
indexName: 'YOUR_INDEX',
|
||||
},
|
||||
```
|
||||
|
||||
Apply at [Algolia DocSearch](https://docsearch.algolia.com/apply). It's free for open source.
|
||||
|
||||
---
|
||||
|
||||
## Plugins Worth Adding
|
||||
|
||||
### Client-Side Redirects
|
||||
|
||||
```typescript
|
||||
plugins: [
|
||||
['@docusaurus/plugin-client-redirects', {
|
||||
redirects: [
|
||||
{ from: '/old-page', to: '/new-page' },
|
||||
],
|
||||
}],
|
||||
],
|
||||
```
|
||||
|
||||
Use for moved pages. Don't leave 404s.
|
||||
|
||||
### Ideal Image
|
||||
|
||||
```typescript
|
||||
['@docusaurus/plugin-ideal-image', {
|
||||
quality: 85,
|
||||
max: 1030,
|
||||
min: 640,
|
||||
}],
|
||||
```
|
||||
|
||||
Auto-generates responsive images. Worth it for image-heavy docs.
|
||||
|
||||
---
|
||||
|
||||
## Things I Never Configure
|
||||
|
||||
These defaults are fine:
|
||||
|
||||
- `i18n` (unless you actually have translations ready)
|
||||
- `onDuplicateRoutes` (the default `warn` is fine)
|
||||
- `staticDirectories` (default `static` works)
|
||||
- `titleDelimiter` (the `|` is universal)
|
||||
|
||||
Don't add config for things you're not using. It's clutter.
|
||||
|
||||
---
|
||||
|
||||
## Config Anti-Patterns
|
||||
|
||||
**Don't:** Copy entire example configs and modify
|
||||
**Do:** Start minimal, add what you need
|
||||
|
||||
**Don't:** Set `onBrokenLinks: 'ignore'` to "fix" build errors
|
||||
**Do:** Actually fix the broken links
|
||||
|
||||
**Don't:** Add `customFields` unless you're using them in code
|
||||
**Do:** Keep config lean
|
||||
|
||||
---
|
||||
|
||||
## Environment Variables
|
||||
|
||||
For values that change between environments:
|
||||
|
||||
```typescript
|
||||
const config = {
|
||||
url: process.env.SITE_URL || 'http://localhost:3000',
|
||||
customFields: {
|
||||
apiUrl: process.env.API_URL,
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
Access in components:
|
||||
```javascript
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
const { siteConfig } = useDocusaurusContext();
|
||||
const apiUrl = siteConfig.customFields.apiUrl;
|
||||
```
|
||||
@@ -0,0 +1,216 @@
|
||||
# Deployment
|
||||
|
||||
Getting your docs live. Pick the platform that fits your workflow.
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision
|
||||
|
||||
| Platform | Best For | Effort |
|
||||
|----------|----------|--------|
|
||||
| **Vercel** | Teams already using Vercel | Lowest |
|
||||
| **Netlify** | Need redirects, forms, functions | Low |
|
||||
| **GitHub Pages** | Open source, simple hosting | Low |
|
||||
| **Cloudflare Pages** | Global performance, free tier | Low |
|
||||
|
||||
**My recommendation:** Vercel or Netlify for most projects. GitHub Pages if you want everything in one repo.
|
||||
|
||||
---
|
||||
|
||||
## Vercel
|
||||
|
||||
### Setup
|
||||
|
||||
1. Push to GitHub
|
||||
2. Import at vercel.com
|
||||
3. Done—it auto-detects Docusaurus
|
||||
|
||||
### Config (vercel.json, usually not needed)
|
||||
|
||||
```json
|
||||
{
|
||||
"buildCommand": "npm run build",
|
||||
"outputDirectory": "build"
|
||||
}
|
||||
```
|
||||
|
||||
Vercel handles this automatically. Only add if you need overrides.
|
||||
|
||||
---
|
||||
|
||||
## Netlify
|
||||
|
||||
### Setup
|
||||
|
||||
1. Push to GitHub
|
||||
2. Connect at app.netlify.com
|
||||
3. Build command: `npm run build`
|
||||
4. Publish directory: `build`
|
||||
|
||||
### Config (netlify.toml)
|
||||
|
||||
```toml
|
||||
[build]
|
||||
command = "npm run build"
|
||||
publish = "build"
|
||||
|
||||
[[redirects]]
|
||||
from = "/old-path"
|
||||
to = "/new-path"
|
||||
status = 301
|
||||
```
|
||||
|
||||
**Opinion:** Netlify's redirect handling is cleaner than most.
|
||||
|
||||
---
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
### Config
|
||||
|
||||
```typescript
|
||||
// docusaurus.config.ts
|
||||
const config = {
|
||||
url: 'https://username.github.io',
|
||||
baseUrl: '/repo-name/', // or '/' for username.github.io
|
||||
organizationName: 'username',
|
||||
projectName: 'repo-name',
|
||||
trailingSlash: false,
|
||||
};
|
||||
```
|
||||
|
||||
### GitHub Actions (recommended)
|
||||
|
||||
`.github/workflows/deploy.yml`:
|
||||
|
||||
```yaml
|
||||
name: Deploy
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
jobs:
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: npm
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: build
|
||||
|
||||
deploy:
|
||||
needs: build
|
||||
runs-on: ubuntu-latest
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
steps:
|
||||
- uses: actions/deploy-pages@v4
|
||||
id: deployment
|
||||
```
|
||||
|
||||
Enable Pages in repo settings → Pages → Source: GitHub Actions.
|
||||
|
||||
---
|
||||
|
||||
## Cloudflare Pages
|
||||
|
||||
### Setup
|
||||
|
||||
1. Connect repo at pages.cloudflare.com
|
||||
2. Framework: None (not auto-detected well)
|
||||
3. Build command: `npm run build`
|
||||
4. Output directory: `build`
|
||||
|
||||
### Why Cloudflare
|
||||
|
||||
- Fastest global CDN
|
||||
- Generous free tier
|
||||
- Web analytics included
|
||||
|
||||
---
|
||||
|
||||
## Pre-Deployment Checklist
|
||||
|
||||
Before pushing:
|
||||
|
||||
```bash
|
||||
# 1. Build locally first
|
||||
npm run build
|
||||
|
||||
# 2. Test the build
|
||||
npm run serve
|
||||
|
||||
# 3. Check for broken links (build will fail if onBrokenLinks: 'throw')
|
||||
# 4. Verify all images load
|
||||
# 5. Test search works (if Algolia configured)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Custom Domain
|
||||
|
||||
All platforms support custom domains. General steps:
|
||||
|
||||
1. Add domain in platform settings
|
||||
2. Update DNS:
|
||||
- `A` record to platform IP, or
|
||||
- `CNAME` to platform URL
|
||||
3. Wait for SSL certificate (automatic, usually minutes)
|
||||
4. Update `url` in docusaurus.config.ts
|
||||
|
||||
**DNS propagation:** Can take up to 48 hours. Usually much faster.
|
||||
|
||||
---
|
||||
|
||||
## Environment-Specific Builds
|
||||
|
||||
For staging vs production:
|
||||
|
||||
```typescript
|
||||
const isProd = process.env.NODE_ENV === 'production';
|
||||
|
||||
const config = {
|
||||
url: isProd
|
||||
? 'https://docs.example.com'
|
||||
: 'https://staging-docs.example.com',
|
||||
};
|
||||
```
|
||||
|
||||
Or use platform environment variables.
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Build Fails Locally But Worked Before
|
||||
|
||||
```bash
|
||||
rm -rf node_modules .docusaurus
|
||||
npm ci
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Build Works Locally, Fails in CI
|
||||
|
||||
- Check Node.js version matches
|
||||
- Check for case-sensitive filename issues (Linux is case-sensitive, macOS isn't)
|
||||
- Check for absolute paths that only exist on your machine
|
||||
|
||||
### "Page Not Found" After Deploy
|
||||
|
||||
- Check `baseUrl` matches your hosting path
|
||||
- Check `trailingSlash` is consistent
|
||||
- Clear CDN cache if platform supports it
|
||||
@@ -0,0 +1,241 @@
|
||||
# Diátaxis Patterns for Docusaurus
|
||||
|
||||
Templates and patterns for each documentation quadrant.
|
||||
|
||||
---
|
||||
|
||||
## Tutorial Template
|
||||
|
||||
**Purpose:** Take someone from zero to "I built something!"
|
||||
|
||||
**Filename:** `getting-started/your-first-[thing].md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Build Your First [Thing]"
|
||||
description: "Create a working [thing] in 10 minutes"
|
||||
---
|
||||
|
||||
# Build Your First [Thing]
|
||||
|
||||
By the end of this tutorial, you'll have a working [thing] that [does X].
|
||||
|
||||
## What You'll Build
|
||||
|
||||
[Screenshot or diagram of the end result]
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Specific version] of [tool] installed
|
||||
- Basic familiarity with [concept] (see [link] if new)
|
||||
|
||||
## Step 1: [Action verb] the [thing]
|
||||
|
||||
[One action, one visible result]
|
||||
|
||||
You should see:
|
||||
```
|
||||
[Expected output]
|
||||
```
|
||||
|
||||
## Step 2: [Next action]
|
||||
|
||||
[Continue pattern...]
|
||||
|
||||
## What You've Built
|
||||
|
||||
You now have a [thing] that [capability].
|
||||
|
||||
**Next steps:**
|
||||
- [Link to how-to guide for customization]
|
||||
- [Link to explanation of how it works]
|
||||
```
|
||||
|
||||
**Tutorial Anti-patterns:**
|
||||
- "First, let's understand how X works..." → Link instead
|
||||
- "You can also do Y..." → One path only
|
||||
- "This is simple..." → Never
|
||||
|
||||
---
|
||||
|
||||
## How-To Guide Template
|
||||
|
||||
**Purpose:** Help someone accomplish a specific task.
|
||||
|
||||
**Filename:** `guides/how-to-[verb]-[thing].md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "How to [Verb] [Thing]"
|
||||
description: "[Outcome] in [context]"
|
||||
---
|
||||
|
||||
# How to [Verb] [Thing]
|
||||
|
||||
[One sentence: what this accomplishes]
|
||||
|
||||
## What You'll Need
|
||||
|
||||
- [Prerequisite 1]
|
||||
- [Prerequisite 2]
|
||||
|
||||
## Steps
|
||||
|
||||
### 1. [Action]
|
||||
|
||||
```bash
|
||||
command here
|
||||
```
|
||||
|
||||
### 2. [Action]
|
||||
|
||||
[Instructions...]
|
||||
|
||||
## Verification
|
||||
|
||||
[How to confirm it worked]
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**[Symptom]:** [Quick fix or link to explanation]
|
||||
```
|
||||
|
||||
**How-to Anti-patterns:**
|
||||
- Teaching concepts (that's a tutorial)
|
||||
- Listing all options (that's reference)
|
||||
- Explaining why (that's explanation)
|
||||
|
||||
---
|
||||
|
||||
## Reference Template
|
||||
|
||||
**Purpose:** Describe what something IS, not how to use it.
|
||||
|
||||
**Filename:** `reference/[category]/[item].md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "[Component/API/Config] Reference"
|
||||
description: "Complete reference for [thing]"
|
||||
---
|
||||
|
||||
# [Thing] Reference
|
||||
|
||||
[One sentence: what this is]
|
||||
|
||||
## Properties
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `name` | `string` | required | Brief description |
|
||||
| `enabled` | `boolean` | `true` | Brief description |
|
||||
|
||||
## Examples
|
||||
|
||||
```javascript
|
||||
// Minimal
|
||||
{ name: "example" }
|
||||
|
||||
// Full
|
||||
{
|
||||
name: "example",
|
||||
enabled: true,
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
## Related
|
||||
|
||||
- [Link to how-to guide using this]
|
||||
- [Link to explanation of design]
|
||||
```
|
||||
|
||||
**Reference Anti-patterns:**
|
||||
- "To use this, first..." → That's a how-to
|
||||
- "This is useful when..." → That's explanation
|
||||
- Incomplete tables (every prop documented)
|
||||
|
||||
---
|
||||
|
||||
## Explanation Template
|
||||
|
||||
**Purpose:** Help someone understand WHY.
|
||||
|
||||
**Filename:** `concepts/[topic].md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: "Understanding [Concept]"
|
||||
description: "Why [thing] works the way it does"
|
||||
---
|
||||
|
||||
# Understanding [Concept]
|
||||
|
||||
[Hook: why this matters to the reader]
|
||||
|
||||
## The Problem
|
||||
|
||||
[What challenge does this solve?]
|
||||
|
||||
## How [Product] Approaches This
|
||||
|
||||
[Your design decision and reasoning]
|
||||
|
||||
## Trade-offs
|
||||
|
||||
| Approach | Pros | Cons |
|
||||
|----------|------|------|
|
||||
| [Option A] | ... | ... |
|
||||
| [Option B] | ... | ... |
|
||||
|
||||
**We chose [X] because [reasoning].**
|
||||
|
||||
## When to Choose Differently
|
||||
|
||||
[Acknowledge alternatives have merit in certain contexts]
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [External resource]
|
||||
- [Related concept in these docs]
|
||||
```
|
||||
|
||||
**Explanation Anti-patterns:**
|
||||
- Step-by-step instructions (how-to)
|
||||
- Property tables (reference)
|
||||
- "Let's build..." (tutorial)
|
||||
|
||||
---
|
||||
|
||||
## Deciding Which Type
|
||||
|
||||
Ask yourself:
|
||||
|
||||
```
|
||||
Is the reader trying to LEARN?
|
||||
├── Yes → Tutorial
|
||||
└── No
|
||||
└── Are they trying to DO something specific?
|
||||
├── Yes → How-to Guide
|
||||
└── No
|
||||
└── Are they trying to LOOK UP information?
|
||||
├── Yes → Reference
|
||||
└── No → Explanation
|
||||
```
|
||||
|
||||
**If you're unsure:** Write it as a how-to first. They're the most commonly needed and easiest to split later.
|
||||
|
||||
---
|
||||
|
||||
## Connecting the Quadrants
|
||||
|
||||
Good docs link between types:
|
||||
|
||||
- **Tutorial** → "To learn more about why this works, see [Explanation]"
|
||||
- **Tutorial** → "For the full API, see [Reference]"
|
||||
- **How-to** → "Prerequisites: complete [Tutorial] first"
|
||||
- **How-to** → "For all options, see [Reference]"
|
||||
- **Reference** → "For a walkthrough, see [How-to]"
|
||||
- **Explanation** → "To try this yourself, see [Tutorial]"
|
||||
|
||||
Never dead-end a reader. Always point them forward.
|
||||
@@ -0,0 +1,276 @@
|
||||
# Writing Guide
|
||||
|
||||
Voice, tone, and language standards for documentation.
|
||||
|
||||
---
|
||||
|
||||
## Voice Principles
|
||||
|
||||
### Be Direct
|
||||
|
||||
Not: "It should be noted that the configuration file needs to be updated."
|
||||
Yes: "Update the configuration file."
|
||||
|
||||
Not: "Users may find it helpful to restart the server."
|
||||
Yes: "Restart the server."
|
||||
|
||||
### Address the Reader
|
||||
|
||||
Not: "Developers can use the API to..."
|
||||
Yes: "Use the API to..."
|
||||
|
||||
Not: "One might consider..."
|
||||
Yes: "Consider..."
|
||||
|
||||
### Present Tense, Active Voice
|
||||
|
||||
Not: "The file will be created when..."
|
||||
Yes: "The file is created when..."
|
||||
|
||||
Not: "The request is processed by the server."
|
||||
Yes: "The server processes the request."
|
||||
|
||||
---
|
||||
|
||||
## Words That Weaken
|
||||
|
||||
Remove these. They add nothing:
|
||||
|
||||
| Remove | Why |
|
||||
|--------|-----|
|
||||
| simply, just, easily | Implies difficulty is your fault |
|
||||
| obviously, clearly | If it were obvious, you wouldn't write it |
|
||||
| please | Unnecessary in instructions |
|
||||
| in order to | "To" works |
|
||||
| it is important to note that | Just state it |
|
||||
| basically | Delete |
|
||||
| actually | Delete |
|
||||
|
||||
**Before:** "Simply run the following command to easily set up..."
|
||||
**After:** "Run the command to set up..."
|
||||
|
||||
---
|
||||
|
||||
## Inclusive Language
|
||||
|
||||
### Required Replacements
|
||||
|
||||
| Don't Use | Use Instead |
|
||||
|-----------|-------------|
|
||||
| whitelist / blacklist | allowlist / blocklist |
|
||||
| master / slave | primary / replica, main / secondary |
|
||||
| master branch | main branch |
|
||||
| sanity check | confidence check, validation, smoke test |
|
||||
| dummy (value/data) | placeholder, sample, test |
|
||||
| cripple | disable, impair, limit |
|
||||
| blind to | unaware of, ignoring |
|
||||
| crazy, insane | unexpected, surprising, intense |
|
||||
| man-hours | person-hours, engineering hours |
|
||||
| manpower | workforce, staffing |
|
||||
| guys | folks, everyone, team, y'all |
|
||||
| he/she, his/her | they, their |
|
||||
| normal users | typical users, most users |
|
||||
|
||||
### Writing About People
|
||||
|
||||
**Disability:**
|
||||
- Not: "suffers from," "victim of," "wheelchair-bound"
|
||||
- Yes: "has," "uses a wheelchair," "with [condition]"
|
||||
|
||||
**Age:**
|
||||
- Not: "the elderly," "seniors"
|
||||
- Yes: "older adults"
|
||||
|
||||
**Experience level:**
|
||||
- Not: "for dummies," "idiot's guide"
|
||||
- Yes: "introduction," "getting started"
|
||||
|
||||
### Cultural Sensitivity
|
||||
|
||||
- Avoid US-centric examples (Thanksgiving, Super Bowl, Fahrenheit)
|
||||
- Use ISO date format: 2024-01-15, not 01/15/2024
|
||||
- Use 24-hour time or specify timezone
|
||||
- Don't assume everyone celebrates the same holidays
|
||||
|
||||
---
|
||||
|
||||
## Second Person "You"
|
||||
|
||||
Always address the reader directly:
|
||||
|
||||
Not: "The user should configure their settings."
|
||||
Yes: "Configure your settings."
|
||||
|
||||
Not: "Developers will need to install..."
|
||||
Yes: "Install..."
|
||||
|
||||
**When to use "we":**
|
||||
- Only when the reader is genuinely working WITH you
|
||||
- "We'll build this together" (in a collaborative tutorial)
|
||||
- Never use "we" to mean "our company"
|
||||
|
||||
---
|
||||
|
||||
## Code in Prose
|
||||
|
||||
### Commands
|
||||
|
||||
Use backticks and be specific:
|
||||
|
||||
Not: "Run the build command."
|
||||
Yes: "Run `npm run build`."
|
||||
|
||||
### Filenames and Paths
|
||||
|
||||
Always in backticks: `docusaurus.config.ts`, `src/pages/`
|
||||
|
||||
### Configuration Values
|
||||
|
||||
In backticks: Set `trailingSlash` to `false`.
|
||||
|
||||
### Placeholders
|
||||
|
||||
Use angle brackets and ALL_CAPS:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/<YOUR_USERNAME>/<REPO_NAME>
|
||||
```
|
||||
|
||||
Not `{username}` or `$USERNAME` in documentation prose.
|
||||
|
||||
---
|
||||
|
||||
## Headings
|
||||
|
||||
### Capitalization
|
||||
|
||||
Use sentence case, not title case:
|
||||
|
||||
Not: "How To Configure Your Build Settings"
|
||||
Yes: "How to configure your build settings"
|
||||
|
||||
### Parallel Structure
|
||||
|
||||
If one heading starts with a verb, they all should:
|
||||
|
||||
**Good:**
|
||||
- Install dependencies
|
||||
- Configure the project
|
||||
- Deploy to production
|
||||
|
||||
**Bad:**
|
||||
- Installation
|
||||
- Configure the project
|
||||
- Deploying to production
|
||||
|
||||
### Depth
|
||||
|
||||
Never go past H3 in a single page. If you need H4, the page is too complex—split it.
|
||||
|
||||
---
|
||||
|
||||
## Lists
|
||||
|
||||
### When to Use Bullets vs. Numbers
|
||||
|
||||
**Numbers:** When order matters (steps, priority)
|
||||
**Bullets:** When order doesn't matter (features, options)
|
||||
|
||||
### List Formatting
|
||||
|
||||
Each item should be grammatically parallel:
|
||||
|
||||
**Good:**
|
||||
- Configure the database
|
||||
- Set up authentication
|
||||
- Deploy the application
|
||||
|
||||
**Bad:**
|
||||
- Database configuration
|
||||
- Set up authentication
|
||||
- The application should be deployed
|
||||
|
||||
### Sentence Fragments OK
|
||||
|
||||
In lists, sentence fragments are fine:
|
||||
|
||||
- Fast builds
|
||||
- Hot reloading
|
||||
- TypeScript support
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Show, Don't Tell
|
||||
|
||||
Not: "The configuration accepts various options for customization."
|
||||
|
||||
Yes:
|
||||
```javascript
|
||||
{
|
||||
theme: 'dark',
|
||||
language: 'en',
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal, Then Complete
|
||||
|
||||
Show the simplest working example first:
|
||||
|
||||
```javascript
|
||||
// Minimal
|
||||
{ name: 'my-project' }
|
||||
```
|
||||
|
||||
Then show comprehensive:
|
||||
|
||||
```javascript
|
||||
// With all options
|
||||
{
|
||||
name: 'my-project',
|
||||
version: '1.0.0',
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### Comments in Code
|
||||
|
||||
Use comments to explain WHY, not WHAT:
|
||||
|
||||
```javascript
|
||||
// Good: Explains reasoning
|
||||
timeout: 30000, // Matches API's default request timeout
|
||||
|
||||
// Bad: States the obvious
|
||||
timeout: 30000, // Set timeout to 30000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Messages
|
||||
|
||||
When documenting errors:
|
||||
|
||||
1. Show the exact error message the user sees
|
||||
2. Explain what caused it
|
||||
3. Give the fix
|
||||
|
||||
```
|
||||
Error: Cannot find module 'react'
|
||||
```
|
||||
|
||||
**Cause:** Dependencies aren't installed.
|
||||
**Fix:** Run `npm install` in your project directory.
|
||||
|
||||
---
|
||||
|
||||
## Checklist Before Publishing
|
||||
|
||||
- [ ] Title describes what the reader will DO
|
||||
- [ ] Description is under 160 characters
|
||||
- [ ] No "simple," "easy," "just," or "obviously"
|
||||
- [ ] All code examples tested and working
|
||||
- [ ] Links to related pages (no dead ends)
|
||||
- [ ] Heading structure: H1 → H2 → H3 only
|
||||
- [ ] Inclusive language throughout
|
||||
Reference in New Issue
Block a user