欢迎使用我的文档

这是加粗文本，行内代码。

功能亮点

• 操作简单
• 主题丰富
• 搜索强大

代码示例

print("Hello, MkDocs!")

注意：使用三个反引号包裹代码，并指定语言可获得语法高亮。

### 4.2 添加更多页面

在 `docs/` 目录下新建 `about.md`，写入介绍内容。要让该页面出现在导航中，需修改 `mkdocs.yml` 的 `nav` 配置。

### 4.3 配置导航与主题

打开 `mkdocs.yml`，进行如下配置：

```yaml
site_name: 我的文档站
site_url: https://example.com/
theme:
  name: material   # 使用 material 主题，若未安装则改为 mkdocs 或 readthedocs
nav:
  - 首页: index.md
  - 关于: about.md
  - 使用指南:
    - 安装: guide/install.md
    - 配置: guide/configuration.md

nav 数组定义了文档页面的层级结构。你可以创建多级目录，只需在 docs/ 下建立对应文件夹，并在 nav 中正确映射路径。

保存配置后，刷新浏览器即可看到动态更新的导航栏。

5. 增强文档能力

5.1 启用 Markdown 扩展

MkDocs 内置了许多扩展，可在 mkdocs.yml 中启用。以下配置开启了代码高亮、任务列表、脚注等常用功能：

markdown_extensions:
  - admonition
  - codehilite
  - footnotes
  - toc:
      permalink: true
  - pymdownx.tasklist:
      custom_checkbox: true

如果你使用 Material 主题，它还支持更多高级扩展（如代码块批注、键盘键、流程图等），可根据官方文档按需添加。

5.2 内置搜索

所有主题都已默认集成客户端搜索引擎。在生成静态站点时，MkDocs 会创建一个 search_index.json 文件，用户可直接在页面上方搜索栏中查找内容，无需后端支持。

5.3 自定义样式与模板

你可以通过主题的 custom_dir 选项覆盖默认模板或添加额外 CSS/JS。例如，在 docs/ 同级创建 overrides/ 目录，然后在 mkdocs.yml 中指定：

theme:
  name: material
  custom_dir: overrides

在 overrides/ 下放置 main.html 或 assets/stylesheets/extra.css 即可实现个性化定制。

6. 构建与部署

6.1 构建静态文件

当你对文档满意后，在项目根目录运行：

mkdocs build

此命令会在目录中生成一个 site/ 文件夹，里面包含完整的 HTML、CSS、JavaScript 等静态资源。你可以直接将这个文件夹的内容上传到任何 Web 服务器。

6.2 部署到 GitHub Pages

如果你将文档源码托管在 GitHub 上，部署到 GitHub Pages 只需一条命令：

mkdocs gh-deploy

该命令会自动构建文档，并推送到仓库的 gh-pages 分支，稍后即可通过 https://你的用户名.github.io/仓库名 访问。

确保你的仓库已设置为使用 gh-pages 分支作为 GitHub Pages 源（在仓库设置中可配置）。

6.3 部署到其他平台

由于构建产物是纯静态文件，你同样可以轻松部署到：

• Netlify / Vercel：连接 Git 仓库，设置构建命令为 mkdocs build，发布目录为 site
• 云服务器：使用 Nginx、Apache 或 Caddy 配置站点根目录指向 site 文件夹
• 对象存储（OSS）：将 site/ 内容上传至阿里云 OSS、AWS S3 等，配合 CDN 加速

7. 进阶技巧与生态

7.1 常见插件推荐

MkDocs 通过插件扩展工作流。安装插件后，在 mkdocs.yml 中配置 plugins 列表即可。以下为一些实用插件：

• search（内置）：静态搜索。
• mkdocs-minify-plugin：压缩 HTML/JS/CSS，提升加载速度。
• mkdocs-git-revision-date-localized-plugin：自动显示每页的最后更新日期。
• mkdocs-macros-plugin：允许在 Markdown 中使用 Jinja2 变量和宏。
• mkdocs-with-pdf：将文档导出为 PDF。

安装示例：

pip install mkdocs-minify-plugin

然后在 mkdocs.yml 中添加：

plugins:
  - search
  - minify:
      minify_html: true

7.2 多版本管理

如果你需要维护多个版本的文档（如 v1.0、v2.0），可以使用 mike 工具（Material 主题官方推荐）。它通过将不同版本构建到子目录，并提供版本选择器。

安装与使用：

pip install mike
mike deploy 1.0
mike set-default 1.0
mike serve

部署到 GitHub Pages 时，执行 mike deploy --push 1.0 即可。

7.3 使用草稿页面

在 mkdocs.yml 中，通过 draft_docs 配置可以指定草稿页面，这些页面在构建时不会被包含：

draft_docs:
  - draft-*.md
  - WIP/**