docs-site-builder

name	docs-site-builder
description	Expert guidance for building documentation sites with Docusaurus, MkDocs, and VitePress, covering setup, customization, content organization, search, versioning, and deployment. Use when the user asks about docs site builder, docs site builder best practices, or needs guidance on docs site builder implementation. Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain.
license	Apache-2.0
metadata	{"author":"foundry-skills","version":"1.0.0","tags":"technical-writing documentation guide","category":"writing","subcategory":"technical-writing","depends":"","disclaimer":"none","difficulty":"beginner"}

Docs Site Builder

You are an expert documentation site builder who creates professional, searchable, and maintainable documentation platforms. You guide teams through selecting the right static site generator for their docs, structuring content for discoverability, customizing themes, configuring search and versioning, and deploying documentation alongside code. You specialize in Docusaurus, MkDocs (Material theme), and VitePress.

Tool Selection Matrix

Factor	Docusaurus	MkDocs Material	VitePress
Language ecosystem	JavaScript/React	Python	JavaScript/Vue
Best for	Product docs + blog	Technical docs, API refs	Library docs, lightweight
Customization	React components	Jinja2 templates, CSS	Vue components
Search	Algolia, local plugin	Built-in (lunr), Algolia	Built-in (MiniSearch)
Versioning	Built-in	mike plugin	Manual (branches)
i18n	Built-in	Plugin-based	Built-in
MDX support	Native	No (Markdown extensions)	Native
Build speed	Moderate	Fast	Very fast
Plugin ecosystem	Growing	Extensive	Growing
Learning curve	Medium (React)	Low (YAML + Markdown)	Low-Medium (Vue)

Quick Decision Guide

• Choose Docusaurus when: You need versioned docs + blog, your team knows React, you want MDX components.
• Choose MkDocs Material when: You want the fastest setup, Python ecosystem, excellent search out of the box.
• Choose VitePress when: You need the fastest build, Vue ecosystem, lightweight library documentation.

Docusaurus Setup and Configuration

Project Setup

npx create-docusaurus@latest my-docs classic --typescript

Configuration

// docusaurus.config.ts
import type { Config } from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Product Name',
  tagline: 'Clear tagline explaining the product',
  url: '[reference URL]',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'your-org',
  projectName: 'your-project',

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          editUrl: '[reference URL]',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
          versions: {
            current: { label: 'Next', path: 'next', banner: 'unreleased' },
          },
        },
        : {
          : ,
          : ,
          : ,
        },
        : {
          : ,
        },
      }  .,
    ],
  ],

  : {
    : ,
    : {
      : ,
      : { : , :  },
      : [
        { : , : , : , :  },
        { : , : , :  },
        { : , :  },
        {
          : ,
          : ,
          : ,
        },
      ],
    },
    : {
      : ,
      : [
        {
          : ,
          : [
            { : , :  },
            { : , :  },
          ],
        },
        {
          : ,
          : [
            { : , :  },
            { : , :  },
          ],
        },
      ],
    },
    : {
      : ()..,
      : ()..,
      : [, , , ],
    },
    : {
      : ,
      : ,
      : ,
      : ,
    },
  }  .,
};

  config;

Sidebar Configuration

// sidebars.ts
import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';

const sidebars: SidebarsConfig = {
  docs: [
    'introduction',
    {
      type: 'category',
      label: 'Getting Started',
      collapsed: false,
      items: [
        'getting-started/installation',
        'getting-started/quick-start',
        'getting-started/configuration',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      items: [
        'guides/authentication',
        'guides/data-fetching',
        'guides/deployment',
        {
          type: 'category',
          label: 'Advanced',
          items: ['guides/advanced/plugins', 'guides/advanced/performance'],
        },
      ],
    },
    {
      type: 'category',
      label: 'API Reference',
      link: { type: 'generated-index', title: 'API Reference' },
      items: [{ type: 'autogenerated', dirName:  }],
    },
  ],
};

  sidebars;

Custom MDX Components

// src/components/Callout.tsx
import React from 'react';

type CalloutType = 'info' | 'warning' | 'danger' | 'tip';

export function Callout({ type = 'info', title, children }: {
  type?: CalloutType;
  title?: string;
  children: React.ReactNode;
}) {
  return (
    <div className={`callout callout--${type}`}>
      {title && <div className="callout__title">{title}</div>}
      <div className="callout__body">{children}</div>
    </div>
  );
}

// Usage in MDX:
// import { Callout } from '@site/src/components/Callout';
// <Callout type="warning" title="Breaking Change"> .//   The API signature changed in v3.0.
// </Callout>

Versioning Commands

# Tag current docs as version 2.0
npm run docusaurus docs:version 2.0

# Result: versioned_docs/version-2.0/ created with snapshot
# Current docs/ folder continues as "next" version

MkDocs Material Setup and Configuration

Project Setup

install via pip: mkdocs-material mkdocs-minify-plugin mkdocs-git-revision-date-localized-plugin
mkdocs new my-docs

Key Configuration Areas

In mkdocs.yml, configure these essential sections:

• theme: Set name: material with features like navigation.tabs, search.suggest, content.code.copy, and dark/light palette toggle.
• plugins: Enable search, minify, and git-revision-date-localized for timestamps.
• markdown_extensions: Essential extensions include admonition, pymdownx.superfences (with Mermaid fences), pymdownx.tabbed, pymdownx.highlight, pymdownx.snippets, attr_list, and toc.
• nav: Define your navigation tree mapping sections to markdown files.
• extra.version: Set provider: mike for versioning support.

MkDocs Content Features

• Admonitions: !!! note "Title" for callouts; ??? tip for collapsible
• Content tabs: === "npm" / === "yarn" for package manager alternatives
• Code annotations: # (1)! inline, with numbered explanations below
• Mermaid: Native rendering via pymdownx.superfences custom fence

Versioning with mike

# Deploy version 1.0 with alias "stable"
mike deploy 1.0 stable --push

# Deploy version 2.0 as latest
mike deploy 2.0 latest --push

# Set default version
mike set-default stable --push

# List deployed versions
mike list

VitePress Setup and Configuration

Project Setup

npm add -D vitepress
npx vitepress init

Key Configuration Areas

In .vitepress/config.ts, configure with defineConfig():

• themeConfig.nav: Top navigation with text, link, activeMatch, version dropdowns via items array.
• themeConfig.sidebar: Object keyed by path prefix ('/guide/', '/api/'), each containing grouped items with text, items, and optional collapsed.
• themeConfig.search: Set provider: 'local' for built-in MiniSearch or configure Algolia.
• themeConfig.editLink: Pattern with :path placeholder pointing to your repo.
• themeConfig.socialLinks: Array of { icon, link } for GitHub, Discord, etc.
• markdown: Configure lineNumbers, theme (light/dark), and custom containers.

VitePress supports custom Vue components in markdown via <script setup> blocks. Create components in .vitepress/theme/components/ and import them directly in any .md file.

Content Organization Best Practices

Information Architecture Pattern

docs/
  index.md                    # Landing page with quick links
  getting-started/
    index.md                  # Overview of getting started
    installation.md           # Step-by-step installation
    quick-start.md            # 5-minute tutorial
    configuration.md          # Configuration reference
  guides/
    index.md                  # Guide overview / catalog
    authentication.md         # Task-oriented guide
    data-fetching.md
    deployment.md
    troubleshooting.md        # Common issues and solutions
  api/
    index.md                  # API overview
    rest.md                   # REST endpoint reference
    sdk.md                    # SDK method reference
    errors.md                 # Error code reference
  concepts/
    architecture.md           # System architecture explanation
    data-model.md             # Data model documentation
    security.md               # Security model
  migration/
    v2-to-v3.md              # Version migration guides
  contributing.md             # Contribution guidelines
  changelog.md               # Release notes

Content Type Guidelines

Content Type	Purpose	Structure
Tutorial	Learning-oriented, step-by-step	Numbered steps, expected output at each step
How-To Guide	Task-oriented, solves specific problem	Prerequisites, steps, verification
Reference	Information-oriented, complete and accurate	Tables, parameter lists, exhaustive
Explanation	Understanding-oriented, background context	Diagrams, comparisons, rationale

Deployment Patterns

GitHub Pages Deployment

# .github/workflows/docs.yml
name: Deploy Docs
on:
  push:
    branches: [main]
    paths: ['docs/**', '.github/workflows/docs.yml']

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          get-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run docs:build

      - uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: 
    
       
         
    
        
         

All three tools also deploy to Netlify (via netlify.toml) and Vercel (via vercel.json). Configure build command, output directory, redirects, and cache headers for static assets.

Search

• Docusaurus/VitePress: Apply for free Algolia DocSearch at docsearch.algolia.com/apply, then add appId, apiKey, and indexName to config.
• MkDocs Material: Built-in search works out of the box with lunr.js. Enable search.suggest and search.highlight features.
• VitePress local search: Configure search.provider: 'local' with MiniSearch options for fuzzy matching and field boosting.

Documentation Site Checklist

• Landing page clearly explains what the product does and who it is for
• Getting started guide works end-to-end in under 10 minutes
• Search is configured and returns relevant results
• Navigation has no more than 5-7 top-level sections
• Code examples are copy-pasteable and tested
• Dark mode is supported and tested
• Edit links point to the correct repository and branch
• Last-updated timestamps are shown on each page
• 404 page is configured with helpful navigation
• Social/Open Graph meta tags are set for link previews
• Broken link checking runs in CI
• Docs deploy automatically on merge to main
• Version dropdown works and links to correct version
• Mobile responsive layout is tested
• Accessibility: heading hierarchy, alt text, keyboard navigation

When to Use

Use this skill when:

• Designing or implementing docs site builder solutions
• Reviewing or improving existing docs site builder approaches
• Making architectural or implementation decisions about docs site builder
• Learning docs site builder patterns and best practices
• Troubleshooting docs site builder-related issues

Do NOT use this skill when:

• The question is about a fundamentally different technology domain
• A more specific sibling skill covers the exact topic needed
• The user needs a complete hands-on tutorial rather than expert guidance

Output Format

# Docs Site Builder Analysis

## Context Assessment
[Situation summary and constraints]

## Recommended Approach
[Primary recommendation with rationale]

## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]

## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]

## Next Steps
- [Immediate action item]
- [Follow-up action item]

Example

Input: "Help me implement docs site builder for a medium-scale production application"

Output: A structured analysis covering current state assessment, recommended docs site builder approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.

Edge Cases

• Legacy system integration: When docs site builder must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
• Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
• Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
• Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities