documentation-site-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation Site Setup

文档网站搭建

Overview

概述

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

使用Docusaurus、MkDocs、VitePress和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

文档网站搭建
API文档门户
产品文档站点
技术文档中心
静态网站生成
GitHub Pages部署
多版本文档

Docusaurus Setup

Docusaurus 搭建指南

Installation

安装步骤

bash

undefined

bash

undefined

Create new Docusaurus site

npx create-docusaurus@latest my-docs classic

cd my-docs

npx create-docusaurus@latest my-docs classic

cd my-docs

Install dependencies

npm install

Start development server

npm start

undefined

npm start

undefined

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

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

配置说明

javascript

// 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',
    },
  },
};

javascript

// 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

侧边栏配置

javascript

// 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',
      ],
    },
  ],
};

javascript

// 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

版本管理

bash

undefined

bash

undefined

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

undefined

undefined

Deployment

部署步骤

bash

undefined

bash

undefined

Build for production

npm run build

Deploy to GitHub Pages

GIT_USER=<username> npm run deploy

---

GIT_USER=<username> npm run deploy

---

MkDocs Setup

MkDocs 搭建指南

Installation

安装步骤

bash

undefined

bash

undefined

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

undefined

mkdocs serve

undefined

Project Structure

项目结构

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

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

Configuration

配置说明

yaml

undefined

yaml

undefined

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

undefined

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/

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

undefined

Admonitions

提示框使用

markdown

!!! 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

markdown

!!! 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

部署步骤

bash

undefined

bash

undefined

Build site

mkdocs build

Deploy to GitHub Pages

mkdocs gh-deploy

---

mkdocs gh-deploy

---

VitePress Setup

VitePress 搭建指南

Installation

安装步骤

bash

undefined

bash

undefined

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


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


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

Configuration

配置说明

javascript

// 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'
    }
  }
}

javascript

// 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

GitBook 搭建指南

Installation

安装步骤

bash

undefined

bash

undefined

Install GitBook CLI

npm install -g gitbook-cli

Initialize book

gitbook init

Start development server

gitbook serve

undefined

gitbook serve

undefined

Project Structure

项目结构

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

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

Configuration

配置说明

json

{
  "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"
    }
  }
}

json

{
  "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"
    }
  }
}

目录设置

markdown

undefined

markdown

undefined

Summary

Introduction

Introduction

Getting Started

Installation
Quick Start

Installation
Quick Start

Guides

Tutorial
Best Practices

Tutorial
Best Practices

API Reference

Overview
Endpoints

---

Overview
Endpoints

---

GitHub Pages Deployment

GitHub Pages 部署

Workflow

工作流配置

yaml

undefined

yaml

undefined

.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

---

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

DNS 配置

undefined

undefined

Add CNAME record

docs.example.com -> username.github.io

undefined

docs.example.com -> username.github.io

undefined

GitHub Pages Settings

GitHub Pages 设置

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

进入仓库设置 > Pages
将源设置为
```
gh-pages
```
分支
添加自定义域名：
```
docs.example.com
```
启用“强制HTTPS”

Search Integration

搜索集成

Algolia DocSearch

javascript

// 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',
    },
  },
};

javascript

// 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

本地搜索

bash

undefined

bash

undefined

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

使用过时的框架
跳过搜索功能
忽略移动端适配
使用加载缓慢的资源
跳过无障碍功能
忽视SEO优化