基于 GitHub + MkDocs 构建 GitHub.io 文档项目教程基于 GitHub + MkDocs 构建

基于 GitHub + MkDocs 构建 GitHub.io 文档项目教程

GitHub Pages（github.io）结合 MkDocs 可以快速搭建专业美观的文档网站，效果如下。

线上体验地址：xiaomingx.github.io

以下是完整实现步骤：

1. 准备工作

拥有 GitHub 账号（注册地址）
安装 Git 并配置用户信息（git config --global user.name 和 user.email）
安装 Python 环境（3.6+），用于运行 MkDocs
了解基础 Markdown 语法（文档内容编写）

2. 创建文档仓库

方式一：独立文档仓库（推荐）

登录 GitHub，点击右上角 "+" → "New repository"
仓库命名必须为：用户名.github.io（例如 devteam.github.io）
勾选 "Initialize this repository with a README"
选择 "Public"（GitHub Pages 免费版要求）
点击 "Create repository"

方式二：现有项目的文档分支

若为现有项目添加文档，可在项目仓库中创建 gh-pages 分支
或在主分支中创建 docs 文件夹专门存放文档

3. 安装并配置 MkDocs

安装 MkDocs

# 安装 MkDocs
pip install mkdocs

# 推荐安装 Material 主题（美观且功能丰富）
pip install mkdocs-material

初始化项目

# 克隆 GitHub 仓库到本地
git clone https://github.com/用户名/用户名.github.io.git
cd 用户名.github.io

# 初始化 MkDocs 项目（会自动创建基础目录结构）
mkdocs new .

目录结构说明

初始化后会生成以下结构：

├── docs/                 # 存放所有 Markdown 文档
│   └── index.md          # 首页内容
├── mkdocs.yml            # 配置文件（主题、导航等）
└── README.md

4. 编写与预览文档

编辑配置文件

修改 mkdocs.yml 配置主题和导航：

site_name: 我的文档站点       # 网站名称
theme:
  name: material             # 使用 Material 主题
  features:
    - navigation.tabs        # 标签式导航
    - search.suggest         # 搜索建议
    - search.highlight       # 搜索高亮
nav:                         # 文档导航结构
  - 首页: index.md
  - 快速开始:
    - 安装: getting-started/installation.md
    - 入门指南: getting-started/quickstart.md
  - 高级用法: usage/advanced.md

编写文档内容

在 docs 目录下创建 Markdown 文件（如 getting-started/installation.md）
使用 Markdown 语法编写文档内容，支持图片、表格、代码块等

本地预览

# 启动本地服务器（默认地址：http://127.0.0.1:8000）
mkdocs serve

修改内容会实时刷新，方便即时预览效果。

5. 部署到 GitHub Pages

手动部署

# 生成静态文件（输出到 site 目录）
mkdocs build

# 部署到 GitHub Pages（自动推送到 gh-pages 分支）
mkdocs gh-deploy

自动部署（推荐）

使用 GitHub Actions 实现提交代码后自动部署：

在仓库中创建 .github/workflows/deploy-docs.yml 文件
添加以下配置：

name: 自动部署文档
on:
  push:
    branches: [ main ]  # 监听 main 分支的推送
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: 设置 Python 环境
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
          
      - name: 安装依赖
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs mkdocs-material
          
      - name: 构建并部署
        run: mkdocs gh-deploy --force
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

提交配置文件到仓库，后续每次推送到 main 分支都会自动更新文档

6. 访问文档网站

部署成功后，几分钟内即可通过以下地址访问：

基础地址：https://用户名.github.io
若使用自定义域名：配置方法同原教程第6步

7. 功能优化

搜索功能：Material 主题自带，无需额外配置
多版本管理：安装 mike 插件（pip install mike）管理历史版本
自定义样式：在 mkdocs.yml 中通过 extra_css 引入自定义 CSS
添加评论：集成 Giscus（需在配置文件中添加相关设置）
SEO 优化：配置 site_description 和 site_author 提升搜索排名

8. 常见问题解决

部署后样式丢失：检查 mkdocs.yml 中是否使用了绝对路径，建议用相对路径
gh-deploy 失败：确保本地已关联远程仓库，且有推送权限
访问 404：检查仓库命名是否正确（用户名.github.io），或等待 GitHub Pages 生效（通常不超过10分钟）

通过以上步骤，你可以快速搭建一个基于 MkDocs 的专业文档网站，并通过 GitHub Pages 免费托管。