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>
2026-07-30 22:58:08 +03:00
parent ed7c7f0d95
commit a596731f67
6 changed files with 1189 additions and 1 deletions
@@ -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