MkDocs 配置示例¶

什么是 MkDocs？¶

MkDocs 是一个快速、简单且华丽的静态网站生成器，专门用于构建项目文档。

特点¶

零配置，开箱即用
支持 Markdown
实时预览
响应式设计
支持主题定制
支持插件扩展

安装¶

Bash

# 安装 MkDocs
pip install mkdocs

# 安装 Material 主题（推荐）
pip install mkdocs-material

# 验证安装
mkdocs --version

项目结构¶

Text Only

project/
├── mkdocs.yml              # MkDocs 配置文件
├── docs/
│   ├── index.md            # 首页
│   ├── 01-getting-started/
│   │   ├── index.md
│   │   ├── installation.md
│   │   └── quickstart.md
│   ├── 02-guides/
│   │   ├── index.md
│   │   ├── login.md
│   │   └── authentication.md
│   ├── 03-api/
│   │   ├── index.md
│   │   └── endpoints.md
│   ├── 04-architecture/
│   │   ├── index.md
│   │   └── design.md
│   └── 05-faq/
│       └── index.md
└── site/                   # 生成的网站（自动创建）

mkdocs.yml 配置¶

YAML

# 项目信息
site_name: 兵卒陪练管理系统
site_description: ASP.NET Core 8.0 MVC Web 应用
site_author: 开发团队
site_url: https://docs.bingzu.top

# 主题配置
theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: blue
      accent: blue
    - scheme: slate
      primary: blue
      accent: blue
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.tabs.link
    - content.code.copy

# 导航结构
nav:
  - 首页: index.md
  - 快速开始:
      - 概述: 01-getting-started/index.md
      - 安装: 01-getting-started/installation.md
      - 快速开始: 01-getting-started/quickstart.md
  - 使用指南:
      - 概述: 02-guides/index.md
      - 登录功能: 02-guides/login.md
      - 认证系统: 02-guides/authentication.md
      - 数据管理: 02-guides/data-management.md
  - API 文档:
      - 概述: 03-api/index.md
      - 登录接口: 03-api/login.md
      - 用户接口: 03-api/users.md
  - 架构设计:
      - 概述: 04-architecture/index.md
      - 系统设计: 04-architecture/design.md
      - 数据库设计: 04-architecture/database.md
  - 常见问题: 05-faq/index.md

# 插件
plugins:
  - search:
      lang: zh
  - minify:
      minify_html: true
      minify_css: true
      minify_js: true

# Markdown 扩展
markdown_extensions:
  - pymdownx.highlight:
      use_pygments: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.emoji:
      emoji_index: pymdownx.emoji.twemoji
      emoji_generator: pymdownx.emoji.to_svg
  - admonition
  - toc:
      permalink: true
  - tables
  - attr_list

# 版权信息
copyright: Copyright &copy; 2026 兵卒陪练管理系统

# 额外配置
extra:
  version: 2.0
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/your-repo
    - icon: fontawesome/brands/wechat
      link: https://bingzu.top

常用命令¶

Bash

# 启动本地预览服务器
mkdocs serve

# 构建静态网站
mkdocs build

# 部署到 GitHub Pages
mkdocs gh-deploy

# 清理构建文件
mkdocs build --clean

文档示例¶

index.md（首页）¶

Markdown

# 兵卒陪练管理系统

欢迎来到兵卒陪练管理系统文档。

## 快速导航

- [快速开始](01-getting-started/index.md) - 5 分钟快速上手
- [使用指南](02-guides/index.md) - 详细的功能说明
- [API 文档](03-api/index.md) - 完整的 API 参考
- [架构设计](04-architecture/index.md) - 系统架构和设计

## 主要功能

- ✅ 用户登录和认证
- ✅ 陪练信息管理
- ✅ 工资计算和审核
- ✅ 数据导入导出

## 技术栈

- ASP.NET Core 8.0
- Bootstrap 5
- 微信云开发

## 获取帮助

- 📖 查看 [常见问题](05-faq/index.md)
- 📧 联系客服：189-5517-3776
- 💬 微信客服：扫描网站中的二维码

02-guides/login.md（登录指南）¶

Markdown

# 登录功能

## 概述

系统支持两种登录方式：密码登录和短信登录。

## 密码登录

### 步骤

1. 输入手机号
2. 输入密码
3. 输入验证码（失败 1 次后显示）
4. 点击登录

### 验证码规则

- 失败 1 次后显示验证码
- 失败 5 次后账户锁定 15 分钟
- 失败次数基于 Phone + IP 计算

### 常见问题

**Q: 忘记密码怎么办？**
A: 使用短信登录，然后在个人中心修改密码。

**Q: 账户被锁定怎么办？**
A: 等待 15 分钟后重试，或联系客服。

## 短信登录

### 步骤

1. 输入手机号
2. 点击"获取验证码"
3. 输入收到的验证码
4. 点击登录

### 验证码规则

- 有效期：5 分钟
- 失败 5 次后禁用"获取验证码"按钮 15 分钟
- 旧验证码未失效时不允许重发

## 相关文档

- [登录设计文档](../../docs/01-active/LOGIN/login_design_final.md)
- [快速参考](../../docs/01-active/LOGIN/login_quick_reference.md)

GitHub Actions 自动发布¶

.github/workflows/docs.yml¶

YAML

name: Deploy Documentation

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - 'mkdocs.yml'

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

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          pip install mkdocs mkdocs-material

      - name: Build documentation
        run: mkdocs build

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

部署选项¶

选项 1：GitHub Pages（免费）¶

Bash

# 一键部署
mkdocs gh-deploy

选项 2：自托管（Nginx）¶

Bash

# 构建网站
mkdocs build

# 复制到 Nginx
cp -r site/* /var/www/docs/

# 配置 Nginx
server {
    listen 80;
    server_name docs.bingzu.top;

    root /var/www/docs;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

选项 3：Docker¶

Docker

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

RUN mkdocs build

FROM nginx:alpine
COPY --from=0 /app/site /usr/share/nginx/html

最佳实践¶

1. 文档结构¶

Text Only

docs/
├── index.md                    # 首页
├── 01-getting-started/         # 快速开始
├── 02-guides/                  # 使用指南
├── 03-api/                     # API 文档
├── 04-architecture/            # 架构设计
└── 05-faq/                     # 常见问题

2. 文档质量¶

每个页面包含目录
使用清晰的标题层级
包含代码示例
包含相关链接

3. 版本管理¶

YAML

# mkdocs.yml
extra:
  version: 2.0
  last_updated: 2026-03-15

4. 搜索优化¶

使用清晰的标题
包含关键词
避免过长的页面

与当前方案的集成¶

迁移步骤¶

创建 MkDocs 项目
Bash
```
mkdocs new docs-site
```
复制现有文档
Bash
```
cp -r docs/* docs-site/docs/
```
配置 mkdocs.yml
设置导航结构
选择主题
配置插件
本地预览
Bash
```
mkdocs serve
```
部署
Bash
```
mkdocs gh-deploy
```

成本对比¶

方案	成本	优点	缺点
MkDocs + GitHub Pages	免费	完全免费，自动部署	需要 Git 知识
MkDocs + 自托管	服务器成本	完全控制	需要维护
GitBook	$10-20/月	用户体验好	需要付费
Confluence	$5-10/用户/月	企业级功能	成本高

总结¶

MkDocs 是最适合你的方案，因为：

✅ 与 Git 完全集成
✅ 成本低（免费）
✅ 支持自动发布
✅ 支持版本管理
✅ 社区活跃
✅ 易于维护

建议实施步骤： 1. 安装 MkDocs 和 Material 主题 2. 配置 mkdocs.yml 3. 组织现有文档 4. 配置 GitHub Actions 自动发布 5. 部署到 GitHub Pages

最后更新：2026-03-15