⚡

文档网站设置Skill documentation-site-setup

本技能提供如何使用Docusaurus、MkDocs、VitePress和GitBook等工具设置和部署技术文档网站的方法，包括项目结构、配置、版本控制和搜索集成等关键步骤，适用于API文档门户、产品文档站点和静态站点生成。

前端开发 0 次安装 0 次浏览 更新于 3/3/2026

文档网站设置

概览

使用流行的静态网站生成器如Docusaurus、MkDocs、VitePress和GitBook设置专业的文档网站。

何时使用

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

Docusaurus设置

安装

# 创建新的Docusaurus网站
npx create-docusaurus@latest my-docs classic

cd my-docs

# 安装依赖
npm install

# 启动开发服务器
npm start

项目结构

my-docs/
├── docs/                    # 文档页面
│   ├── intro.md
│   ├── tutorial/
│   │   ├── basics.md
│   │   └── advanced.md
│   └── api/
│       └── reference.md
├── blog/                    # 博客文章（可选）
│   ├── 2025-01-15-post.md
│   └── authors.yml
├── src/
│   ├── components/          # React组件
│   ├── css/                 # 自定义CSS
│   └── pages/               # 自定义页面
│       ├── index.js         # 首页
│       └── about.md
├── static/                  # 静态资源
│   └── img/
├── docusaurus.config.js     # 网站配置
├── sidebars.js              # 侧边栏配置
└── package.json

配置

// docusaurus.config.js
module.exports = {
  title: '我的文档',
  tagline: '为开发者提供的全面文档',
  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: '我的文档',
      logo: {
        alt: 'Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: '文档',
        },
        {
          to: '/blog',
          label: '博客',
          position: 'left'
        },
        {
          href: 'https://github.com/myorg/repo',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: '文档',
          items: [
            {
              label: '开始',
              to: '/docs/intro',
            },
            {
              label: 'API参考',
              to: '/docs/api/reference',
            },
          ],
        },
        {
          title: '社区',
          items: [
            {
              label: 'Discord',
              href: 'https://discord.gg/example',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/example',
            },
          ],
        },
      ],
      copyright: `版权所有 © ${new Date().getFullYear()} 我的公司.`,
    },
    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',
    },
  },
};

侧边栏配置

// sidebars.js
module.exports = {
  docs: [
    'intro',
    {
      type: 'category',
      label: '开始',
      items: [
        'getting-started/installation',
        'getting-started/quick-start',
        'getting-started/configuration',
      ],
    },
    {
      type: 'category',
      label: '指南',
      items: [
        'guides/authentication',
        'guides/database',
        'guides/deployment',
      ],
    },
    {
      type: 'category',
      label: 'API参考',
      items: [
        'api/overview',
        'api/endpoints',
        'api/errors',
      ],
    },
  ],
};

版本控制

# 创建版本1.0
npm run docusaurus docs:version 1.0

# 创建的文件：
# - versioned_docs/version-1.0/
# - versioned_sidebars/version-1.0-sidebars.json
# - versions.json

部署

# 为生产构建
npm run build

# 部署到GitHub Pages
GIT_USER=<用户名> npm run deploy

MkDocs设置

安装

# 安装MkDocs
pip install mkdocs

# 安装Material主题
pip install mkdocs-material

# 创建新项目
mkdocs new my-docs
cd my-docs

# 启动开发服务器
mkdocs serve

项目结构

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

配置

# mkdocs.yml
site_name: 我的文档
site_url: https://docs.example.com
site_description: 全面文档
site_author: 你的名字

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

theme:
  name: material
  palette:
    # 浅色模式
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    # 深色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式
  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:
  - 首页: index.md
  - 开始:
    - 安装: getting-started/installation.md
    - 快速开始: getting-started/quick-start.md
  - 指南:
    - 教程: guides/tutorial.md
    - 最佳实践: guides/best-practices.md
  - API参考:
    - 概览: api/overview.md
    - 端点: 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

警告框

!!! note
    这是一个注意事项

!!! tip
    这是一个提示

!!! warning
    这是一个警告

!!! danger
    这是危险的

!!! info "自定义标题"
    带有标题的自定义警告框

部署

# 构建网站
mkdocs build

# 部署到GitHub Pages
mkdocs gh-deploy

VitePress设置

安装

# 创建项目
mkdir my-docs
cd my-docs

# 初始化
npm init -y
npm install -D vitepress

# 创建文档
mkdir docs
echo '# Hello VitePress' > docs/index.md

# 添加脚本到package.json

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

配置

// docs/.vitepress/config.js
export default {
  title: '我的文档',
  description: '全面文档',
  themeConfig: {
    nav: [
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'GitHub', link: 'https://github.com/myorg/repo' }
    ],
    sidebar: {
      '/guide/': [
        {
          text: '开始',
          items: [
            { text: '介绍', link: '/guide/' },
            { text: '安装', link: '/guide/installation' },
            { text: '快速开始', link: '/guide/quick-start' }
          ]
        },
        {
          text: '高级',
          items: [
            { text: '配置', link: '/guide/configuration' },
            { text: '部署', link: '/guide/deployment' }
          ]
        }
      ],
      '/api/': [
        {
          text: 'API参考',
          items: [
            { text: '概览', link: '/api/' },
            { text: '端点', link: '/api/endpoints' }
          ]
        }
      ]
    },
    socialLinks: [
      { icon: 'github', link: 'https://github.com/myorg/repo' }
    ],
    editLink: {
      pattern: 'https://github.com/myorg/repo/edit/main/docs/:path',
      text: '在GitHub上编辑此页面'
    },
    footer: {
      message: '根据MIT许可发布。',
      copyright: '版权所有 © 2025-present 我的公司'
    },
    search: {
      provider: 'local'
    }
  }
}

GitBook设置

安装

# 安装GitBook CLI
npm install -g gitbook-cli

# 初始化书籍
gitbook init

# 启动开发服务器
gitbook serve

项目结构

my-docs/
├── README.md        # 介绍
├── SUMMARY.md       # 目录
├── book.json        # 配置
└── chapters/
    ├── chapter1.md
    └── chapter2.md

配置

{
  "title": "我的文档",
  "description": "全面文档",
  "author": "你的名字",
  "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": "编辑此页面"
    }
  }
}

目录

# 目录

* [介绍](README.md)

## 开始
* [安装](chapters/installation.md)
* [快速开始](chapters/quick-start.md)

## 指南
* [教程](chapters/tutorial.md)
* [最佳实践](chapters/best-practices.md)

## API参考
* [概览](chapters/api-overview.md)
* [端点](chapters/api-endpoints.md)

GitHub Pages部署

工作流程

# .github/workflows/deploy-docs.yml
name: 部署文档

on:
  push:
    branches: [main]

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

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

      - name: 安装依赖
        run: npm ci

      - name: 构建文档
        run: npm run build

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

自定义域名设置

DNS配置

# 添加CNAME记录
docs.example.com -> username.github.io

GitHub Pages设置

  1. 前往仓库Settings > Pages
  2. 设置源为gh-pages分支
  3. 添加自定义域名：docs.example.com
  4. 启用“强制HTTPS”

搜索集成

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

本地搜索

# MkDocs
pip install mkdocs-material[search]

# VitePress（内置）
# 不需要额外设置

最佳实践

✅ 做

  • 使用一致的导航结构
  • 启用搜索功能
  • 为页面添加编辑链接
  • 包含版本选择器以供版本化文档使用
  • 为代码块使用语法高亮
  • 添加暗色模式支持
  • 优化图像和资源
  • 启用分析
  • 添加社交媒体链接
  • 使用响应式设计
  • 包含面包屑
  • 添加目录
  • 在移动设备上测试

❌ 不做

  • 使用过时的框架
  • 跳过搜索功能
  • 忘记移动响应性
  • 使用加载缓慢的资源
  • 跳过辅助功能
  • 忽略SEO优化

资源