# Documentation Systems & Infrastructure

## Static Site Generators

### Docusaurus (Meta)

```bash
# Setup
npx create-docusaurus@latest docs classic
cd docs && npm start

# Structure
docs/
├── docs/           # Documentation pages
├── blog/           # Blog posts
├── src/
│   └── pages/      # Custom pages
└── docusaurus.config.js
```

**docusaurus.config.js:**

```javascript
module.exports = {
  title: "My API",
  tagline: "Build amazing things",
  url: "https://docs.example.com",
  baseUrl: "/",

  themeConfig: {
    navbar: {
      items: [
        { to: "/docs/intro", label: "Docs", position: "left" },
        { to: "/api", label: "API", position: "left" },
      ],
    },

    // Algolia search
    algolia: {
      apiKey: "YOUR_API_KEY",
      indexName: "your_index",
      contextualSearch: true,
    },

    prism: {
      theme: lightCodeTheme,
      darkTheme: darkCodeTheme,
      additionalLanguages: ["python", "rust"],
    },
  },
}
```

### MkDocs (Python)

```yaml
# mkdocs.yml
site_name: My API Documentation
theme:
  name: material
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - search.suggest
    - search.highlight
  palette:
    - scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          options:
            show_source: true
  - git-revision-date-localized

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - admonition
  - codehilite

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api/
```

### VitePress (Vue)

```typescript
// .vitepress/config.ts
export default defineConfig({
  title: "API Docs",
  description: "Developer documentation",

  themeConfig: {
    nav: [
      { text: "Guide", link: "/guide/" },
      { text: "API", link: "/api/" },
    ],

    sidebar: {
      "/guide/": [
        {
          text: "Introduction",
          items: [
            { text: "Getting Started", link: "/guide/getting-started" },
            { text: "Configuration", link: "/guide/config" },
          ],
        },
      ],
    },

    search: {
      provider: "local",
    },

    editLink: {
      pattern: "https://github.com/user/repo/edit/main/docs/:path",
    },
  },
})
```

## Multi-Version Documentation

### Version Switcher

```javascript
// Docusaurus versions
{
  versions: {
    current: {
      label: '2.0 (Next)',
      path: 'next',
    },
  },
  onlyIncludeVersions: ['current', '1.5', '1.4'],
}
```

### Migration Guides

````markdown
# Migration Guide: v1 to v2

## Breaking Changes

### Authentication

**v1:**

```python
client.authenticate(api_key)
```
````

**v2:**

```python
client = Client(api_key=api_key)  # Pass in constructor
```

### Renamed Methods

| v1              | v2              | Notes           |
| --------------- | --------------- | --------------- |
| `get_user()`    | `fetch_user()`  | Async now       |
| `delete_user()` | `remove_user()` | Returns Promise |

## Deprecation Timeline

- v1.x: Supported until Dec 2025
- v2.0: Released Jan 2025
- v2.1: Current (June 2025)

````

## Search Implementation

### Algolia DocSearch

```html
<!-- Add to theme -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />

<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
<script>
  docsearch({
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_API_KEY',
    indexName: 'your_index',
    container: '#docsearch',
  });
</script>
````

### Local Search (Lunr.js)

```javascript
const idx = lunr(function () {
  this.ref("id")
  this.field("title", { boost: 10 })
  this.field("content")

  documents.forEach((doc) => this.add(doc))
})

// Search
const results = idx.search("authentication")
```

## Documentation Testing

### Link Checking

```bash
# linkcheck (Python)
pip install linkchecker
linkchecker http://localhost:3000/docs

# broken-link-checker (Node)
npm install -g broken-link-checker
blc http://localhost:3000 -ro
```

### Code Example Testing

```python
# doctest for Python examples
"""
>>> add(2, 3)
5
>>> add(-1, 1)
0
"""

# Run tests
python -m doctest -v docs/*.md
```

```javascript
// Jest for TypeScript examples
// Extract code blocks and test
import { runExamples } from "./test-docs"

test("API examples work", async () => {
  const examples = extractExamples("./docs/api.md")
  await expect(runExamples(examples)).resolves.toBeTruthy()
})
```

## Performance Optimization

### Build Optimization

```javascript
// Webpack/Vite config
export default {
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ["react", "react-dom"],
        },
      },
    },
  },

  optimizeDeps: {
    include: ["prismjs"],
  },
}
```

### CDN & Caching

```nginx
# nginx.conf
location /docs {
  expires 1y;
  add_header Cache-Control "public, immutable";
}

location ~* \.(html)$ {
  expires 1h;
  add_header Cache-Control "public, must-revalidate";
}
```

## Analytics Integration

### Google Analytics

```javascript
// Docusaurus
gtag: {
  trackingID: 'G-XXXXXXXXXX',
  anonymizeIP: true,
},
```

### Custom Analytics

```javascript
// Track search queries
function trackSearch(query, results) {
  analytics.track("docs_search", {
    query,
    resultCount: results.length,
    timestamp: new Date(),
  })
}
```

## Quick Reference

| Tool       | Best For                      | Tech Stack     |
| ---------- | ----------------------------- | -------------- |
| Docusaurus | React projects, versioning    | React, MDX     |
| MkDocs     | Python projects, simple setup | Python, Jinja2 |
| VitePress  | Vue projects, fast builds     | Vue, Vite      |
| Nextra     | Next.js integration           | React, Next.js |
| Mintlify   | Modern UI, AI search          | React          |

| Search Solution   | Cost             | Features            |
| ----------------- | ---------------- | ------------------- |
| Algolia DocSearch | Free (OSS)       | Fast, typo-tolerant |
| Local (Lunr.js)   | Free             | Offline, no server  |
| Typesense         | Free (self-host) | Privacy-focused     |
| Meilisearch       | Free (self-host) | Fast, relevance     |