Documentation Site Setup

Documentation Site Setup

Overview

Set up professional documentation websites using popular static site generators like Docusaurus, MkDocs, VitePress, and GitBook.

When to Use

• Documentation website setup
• API documentation portals
• Product documentation sites
• Technical documentation hubs
• Static site generation
• GitHub Pages deployment
• Multi-version documentation

Docusaurus Setup

Installation

# Create new Docusaurus site
npx create-docusaurus@latest my-docs classic

cd my-docs

# Install dependencies
npm install

# Start development server
npm start

Project Structure

my-docs/
├── docs/                    # Documentation pages
│   ├── intro.md
│   ├── tutorial/
│   │   ├── basics.md
│   │   └── advanced.md
│   └── api/
│       └── reference.md
├── blog/                    # Blog posts (optional)
│   ├── 2025-01-15-post.md
│   └── authors.yml
├── src/
│   ├── components/          # React components
│   ├── css/                 # Custom CSS
│   └── pages/               # Custom pages
│       ├── index.js         # Homepage
│       └── about.md
├── static/                  # Static assets
│   └── img/
├── docusaurus.config.js     # Site configuration
├── sidebars.js              # Sidebar configuration
└── package.json

Configuration

// docusaurus.config.js
module.exports = {
  title: 'My Documentation',
  tagline: 'Comprehensive documentation for developers',
  url: 'https://docs.example.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'myorg',
  projectName: 'my-docs',

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          editUrl: 'https://github.com/myorg/my-docs/tree/main/',
          showLastUpdateTime: true,
          showLastUpdateAuthor: true,
        },
        blog: {
          showReadingTime: true,
          editUrl: 'https://github.com/myorg/my-docs/tree/main/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],

  themeConfig: {
    navbar: {
      title: 'My Docs',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: 'Docs',
        },
        {
          to: '/blog',
          label: 'Blog',
          position: 'left'
        },
        {
          href: 'https://github.com/myorg/repo',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Getting Started',
              to: '/docs/intro',
            },
            {
              label: 'API Reference',
              to: '/docs/api/reference',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Discord',
              href: 'https://discord.gg/example',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/example',
            },
          ],
        },
      ],
      copyright: `Copyright © ${new Date().getFullYear()} My Company.`,
    },
    prism: {
      theme: require('prism-react-renderer/themes/github'),
      darkTheme: require('prism-react-renderer/themes/dracula'),
      additionalLanguages: ['bash', 'diff', 'json'],
    },
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
};

Sidebar Configuration

// sidebars.js
module.exports = {
  docs: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: [
        'getting-started/installation',
        'getting-started/quick-start',
        'getting-started/configuration',
      ],
    },
    {
      type: 'category',
      label: 'Guides',
      items: [
        'guides/authentication',
        'guides/database',
        'guides/deployment',
      ],
    },
    {
      type: 'category',
      label: 'API Reference',
      items: [
        'api/overview',
        'api/endpoints',
        'api/errors',
      ],
    },
  ],
};

Versioning

# Create version 1.0
npm run docusaurus docs:version 1.0

# Files created:
# - versioned_docs/version-1.0/
# - versioned_sidebars/version-1.0-sidebars.json
# - versions.json

Deployment

# Build for production
npm run build

# Deploy to GitHub Pages
GIT_USER=<username> npm run deploy

MkDocs Setup

Installation

# Install MkDocs
pip install mkdocs

# Install Material theme
pip install mkdocs-material

# Create new project
mkdocs new my-docs
cd my-docs

# Start development server
mkdocs serve

Project Structure

my-docs/
├── docs/
│   ├── index.md
│   ├── getting-started.md
│   ├── api/
│   │   └── reference.md
│   └── guides/
│       └── tutorial.md
├── mkdocs.yml
└── requirements.txt

Configuration

# mkdocs.yml
site_name: My Documentation
site_url: https://docs.example.com
site_description: Comprehensive documentation
site_author: Your Name

repo_name: myorg/repo
repo_url: https://github.com/myorg/repo
edit_uri: edit/main/docs/

theme:
  name: material
  palette:
    # Light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.annotate
    - content.tabs.link

plugins:
  - search
  - minify:
      minify_html: true

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - attr_list
  - md_in_html

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - Guides:
    - Tutorial: guides/tutorial.md
    - Best Practices: guides/best-practices.md
  - API Reference:
    - Overview: api/overview.md
    - Endpoints: api/reference.md

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/myorg
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/myorg
  version:
    provider: mike

Admonitions

!!! note
    This is a note

!!! tip
    This is a tip

!!! warning
    This is a warning

!!! danger
    This is dangerous

!!! info "Custom Title"
    Custom admonition with title

Deployment

# Build site
mkdocs build

# Deploy to GitHub Pages
mkdocs gh-deploy

VitePress Setup

Installation

# Create project
mkdir my-docs
cd my-docs

# Initialize
npm init -y
npm install -D vitepress

# Create docs
mkdir docs
echo '# Hello VitePress' > docs/index.md

# Add scripts to package.json

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

Configuration

// docs/.vitepress/config.js
export default {
  title: 'My Documentation',
  description: 'Comprehensive documentation',
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'GitHub', link: 'https://github.com/myorg/repo' }
    ],
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Installation', link: '/guide/installation' },
            { text: 'Quick Start', link: '/guide/quick-start' }
          ]
        },
        {
          text: 'Advanced',
          items: [
            { text: 'Configuration', link: '/guide/configuration' },
            { text: 'Deployment', link: '/guide/deployment' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API Reference',
          items: [
            { text: 'Overview', link: '/api/' },
            { text: 'Endpoints', link: '/api/endpoints' }
          ]
        }
      ]
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/myorg/repo' }
    ],
    editLink: {
      pattern: 'https://github.com/myorg/repo/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    },
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2025-present My Company'
    },
    search: {
      provider: 'local'
    }
  }
}

GitBook Setup

Installation

# Install GitBook CLI
npm install -g gitbook-cli

# Initialize book
gitbook init

# Start development server
gitbook serve

Project Structure

my-docs/
├── README.md        # Introduction
├── SUMMARY.md       # Table of contents
├── book.json        # Configuration
└── chapters/
    ├── chapter1.md
    └── chapter2.md

Configuration

{
  "title": "My Documentation",
  "description": "Comprehensive documentation",
  "author": "Your Name",
  "language": "en",
  "gitbook": "3.2.3",
  "plugins": [
    "search",
    "prism",
    "-highlight",
    "github",
    "edit-link",
    "versions"
  ],
  "pluginsConfig": {
    "github": {
      "url": "https://github.com/myorg/repo"
    },
    "edit-link": {
      "base": "https://github.com/myorg/repo/edit/main",
      "label": "Edit This Page"
    }
  }
}

Table of Contents

# Summary

* [Introduction](README.md)

## Getting Started
* [Installation](chapters/installation.md)
* [Quick Start](chapters/quick-start.md)

## Guides
* [Tutorial](chapters/tutorial.md)
* [Best Practices](chapters/best-practices.md)

## API Reference
* [Overview](chapters/api-overview.md)
* [Endpoints](chapters/api-endpoints.md)

GitHub Pages Deployment

Workflow

# .github/workflows/deploy-docs.yml
name: Deploy Documentation

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm ci

      - name: Build documentation
        run: npm run build

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

Custom Domain Setup

DNS Configuration

# Add CNAME record
docs.example.com -> username.github.io

GitHub Pages Settings

1. Go to repository Settings > Pages
2. Set source to gh-pages branch
3. Add custom domain: docs.example.com
4. Enable "Enforce HTTPS"

Search Integration

Algolia DocSearch

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
      contextualSearch: true,
      searchParameters: {},
      searchPagePath: 'search',
    },
  },
};

Local Search

# MkDocs
pip install mkdocs-material[search]

# VitePress (built-in)
# No additional setup needed

Best Practices

✅ DO

• Use consistent navigation structure
• Enable search functionality
• Add edit links to pages
• Include version selector for versioned docs
• Use syntax highlighting for code blocks
• Add dark mode support
• Optimize images and assets
• Enable analytics
• Add social media links
• Use responsive design
• Include breadcrumbs
• Add table of contents
• Test on mobile devices

❌ DON'T

• Use outdated frameworks
• Skip search functionality
• Forget mobile responsiveness
• Use slow-loading assets
• Skip accessibility features
• Ignore SEO optimization

Resources

• Docusaurus
• MkDocs
• MkDocs Material
• VitePress
• GitBook
• GitHub Pages
• Algolia DocSearch