搬瓦工搭建 MkDocs 文档网站教程

MkDocs 是一款基于 Python 的静态文档网站生成器，使用 Markdown 编写文档内容，配合 Material for MkDocs 主题可以生成美观专业的文档网站。许多知名开源项目都使用 MkDocs 搭建文档站点。本文将介绍如何在搬瓦工 VPS 上搭建 MkDocs 文档网站。购买搬瓦工 VPS 请参考全部方案，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。

一、安装 Python 和 MkDocs

apt update && apt upgrade -y
apt install python3 python3-pip python3-venv -y

# 创建虚拟环境
python3 -m venv /opt/mkdocs-env
source /opt/mkdocs-env/bin/activate

# 安装 MkDocs 和 Material 主题
pip install mkdocs mkdocs-material
mkdocs --version

二、创建文档项目

cd /opt
mkdocs new mydocs
cd mydocs

2.1 配置 mkdocs.yml

cat > /opt/mydocs/mkdocs.yml << 'EOF'
site_name: 我的文档站
site_url: https://docs.yourdomain.com
site_description: 项目文档网站
site_author: Your Name

theme:
  name: material
  language: zh
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换暗色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换亮色模式
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.tabs.link

plugins:
  - search:
      lang: zh

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details
  - attr_list
  - md_in_html
  - toc:
      permalink: true

nav:
  - 首页: index.md
  - 快速开始:
    - 安装: getting-started/installation.md
    - 配置: getting-started/configuration.md
  - 指南:
    - 基本用法: guide/basic.md
    - 高级功能: guide/advanced.md
  - API 参考: api/reference.md
EOF

2.2 创建文档内容

mkdir -p /opt/mydocs/docs/{getting-started,guide,api}

cat > /opt/mydocs/docs/index.md << 'EOF'
# 欢迎

这是项目的官方文档网站，使用 MkDocs 和 Material 主题搭建。

## 快速导航

- [安装指南](getting-started/installation.md) - 如何安装和配置
- [基本用法](guide/basic.md) - 入门教程
- [API 参考](api/reference.md) - 完整的 API 文档
EOF

cat > /opt/mydocs/docs/getting-started/installation.md << 'EOF'
# 安装指南

本文介绍如何安装和配置项目环境。

## 系统要求

- 操作系统：Linux、macOS 或 Windows
- 运行时环境：根据项目需求而定

## 安装步骤

按照以下步骤完成安装。
EOF

三、构建与部署

3.1 本地预览

source /opt/mkdocs-env/bin/activate
cd /opt/mydocs
mkdocs serve -a 0.0.0.0:8000

3.2 构建静态文件

mkdocs build

生成的静态文件在 site/ 目录下。

3.3 Nginx 部署

apt install nginx -y

cat > /etc/nginx/sites-available/mkdocs.conf << 'EOF'
server {
    listen 80;
    server_name docs.yourdomain.com;
    root /opt/mydocs/site;
    index index.html;

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

    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;

    error_page 404 /404.html;
}
EOF

ln -sf /etc/nginx/sites-available/mkdocs.conf /etc/nginx/sites-enabled/
nginx -t && systemctl restart nginx

四、常用 Material 功能

Material for MkDocs 提供了丰富的文档增强功能，包括告警框、代码标签页、任务列表等。这些功能通过 Markdown 扩展实现，在 mkdocs.yml 中配置后即可使用。

五、自动部署脚本

cat > /opt/mydocs/deploy.sh << 'EOF'
#!/bin/bash
source /opt/mkdocs-env/bin/activate
cd /opt/mydocs
git pull origin main
mkdocs build
echo "[$(date)] MkDocs site deployed"
EOF
chmod +x /opt/mydocs/deploy.sh

六、SSL 证书

apt install certbot python3-certbot-nginx -y
certbot --nginx -d docs.yourdomain.com

七、常见问题

插件安装失败

确保使用虚拟环境中的 pip 安装插件，避免系统 Python 环境冲突。所有 MkDocs 相关的 pip 包都应在同一个虚拟环境中安装。

中文搜索不工作

确认 search 插件配置了 lang: zh。Material 主题内置了中文搜索支持。

总结

MkDocs 配合 Material 主题是搭建文档网站的最佳方案之一，Markdown 编写简单高效，生成的文档美观专业。如果你更偏好 JavaScript 生态的文档工具，可以参考 Docusaurus 或 VitePress。购买搬瓦工 VPS 请访问 bwh81.net，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。