MkDocs 使用指南

MkDocs 是一个快速、简单且功能强大的静态网站生成器，主要用于生成项目文档。它使用 Markdown 格式编写内容，并通过简单的配置文件生成 HTML 网站。本指南将详细介绍如何安装、配置、构建和部署 MkDocs 项目。

1. 安装 MkDocs

MkDocs 需要 Python 环境。以下是安装步骤：

1.1 安装 Python

确保你的系统中已安装 Python 3.6 或更高版本。可以通过以下命令检查：

python --version

如果未安装 Python，请从 Python 官网 下载并安装。

1.2 安装 MkDocs

使用 pip 安装 MkDocs：

pip install mkdocs

验证安装是否成功：

mkdocs --version

1.3 安装主题（可选）

MkDocs 默认使用基本主题，但推荐安装流行的 Material for MkDocs 主题以获得更现代的外观：

pip install mkdocs-material

2. 创建 MkDocs 项目

2.1 初始化项目

在你希望创建文档的目录下运行以下命令：

mkdocs new my-project

这会生成以下结构：

my-project/
├── docs/
│ └── index.md
└── mkdocs.yml

docs/：存放 Markdown 文档的文件夹。

mkdocs.yml：MkDocs 配置文件。

2.2 启动开发服务器

进入项目目录并启动开发服务器：

cd my-project
mkdocs serve

打开浏览器，访问 http://localhost:8000，即可实时预览文档。修改 Markdown 文件后，页面会自动刷新。

3. 配置 MkDocs

MkDocs 的核心配置文件是 mkdocs.yml。以下是一个示例配置：

site_name: 我的项目文档
site_url: https://example.com/
theme:
name: material
language: zh
nav:

• 首页: index.md
• 快速开始: getting-started.md

• 用户指南:

  • 安装: installation.md
  • 配置: configuration.md

plugins:

• search

markdown_extensions:

• pymdownx.highlight
• pymdownx.superfences

3.1 主要配置项说明

site_name：网站名称。

site_url：网站部署后的 URL。

theme：指定主题，例如 material 或 readthedocs。

nav：定义导航结构，支持嵌套菜单。

plugins：启用插件，例如搜索功能。

markdown_extensions：启用 Markdown 扩展以支持高级语法。

3.2 常用主题配置

对于 Material 主题，可以添加以下配置：

theme:
name: material
palette:

primary: indigo
accent: pink

font:

text: Roboto
code: Roboto Mono

features:

- content.code.copy
- content.tabs

4. 编写文档

文档存放在 docs/ 目录下，文件使用 Markdown 格式。以下是一个简单的 index.md 示例：

欢迎使用 MkDocs

这是我的项目文档首页。

简介

MkDocs 是一个静态网站生成器，适合快速构建文档网站。

快速链接

• 安装指南
• 配置说明

4.1 Markdown 扩展

MkDocs 支持多种 Markdown 扩展，例如代码高亮、表格和表情符号。常用扩展包括：

pymdownx.highlight：代码高亮。

pymdownx.superfences：支持嵌套代码块。

toc：自动生成目录。

在 mkdocs.yml 中启用扩展：

markdown_extensions:

• pymdownx.highlight
• pymdownx.superfences
• toc:
  permalink: true

5. 构建和部署

5.1 构建静态网站

运行以下命令生成静态 HTML 文件：

mkdocs build

生成的文件位于 site/ 目录，可直接部署到 Web 服务器。

5.2 部署到 GitHub Pages

MkDocs 提供便捷的 GitHub Pages 部署命令：

mkdocs gh-deploy

这会将 site/ 目录的内容推送到 GitHub 仓库的 gh-pages 分支。确保仓库已启用 GitHub Pages。

5.3 其他部署方式

Netlify：将 site/ 目录拖放到 Netlify 仪表板。

Vercel：将项目与 Vercel 集成，自动部署。

自定义服务器：将 site/ 目录上传到 Web 服务器。

6. 高级功能

6.1 添加插件

MkDocs 支持多种插件，例如：

search：启用搜索功能。

mkdocs-git-revision-date-localized：显示文档的最后更新时间。

安装插件：

pip install mkdocs-git-revision-date-localized

在 mkdocs.yml 中启用：

plugins:

• search
• git-revision-date-localized

6.2 自定义主题

可以自定义 CSS 和 JavaScript 文件。例如，在 docs/ 目录下创建 css/ 文件夹，添加自定义样式：

/ docs/css/custom.css /
h1 {
color: navy;
}

在 mkdocs.yml 中引用：

extra_css:

• css/custom.css

6.3 多语言支持

Material 主题支持多语言，通过 language 设置切换语言：

theme:
name: material
language: zh

7. 常见问题

问题：mkdocs serve 启动后无法访问？

解决：检查端口是否被占用，尝试 mkdocs serve --dev-addr=127.0.0.1:8001。

问题：导航菜单未正确显示？

解决：检查 mkdocs.yml 中的 nav 配置，确保文件路径正确。

问题：部署后页面空白？

解决：确保 site_url 配置正确，且静态文件已正确上传。

8. 参考资源

MkDocs 官方文档

Material for MkDocs

MkDocs 插件列表