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;
+```