MkDocs 配置完全指南：从基础到高级设置

最新推荐文章于 2025-06-05 09:07:27 发布

侯颂翼

最新推荐文章于 2025-06-05 09:07:27 发布

阅读量275

点赞数 3

CC 4.0 BY-SA版权

本文链接：https://blog.csdn.net/gitblog_00739/article/details/148362738

MkDocs 配置完全指南：从基础到高级设置

作为一款优秀的静态网站生成工具，MkDocs 通过简洁的 YAML 配置文件提供了丰富的自定义选项。本文将全面解析 MkDocs 的配置系统，帮助开发者构建更专业的文档网站。

基础配置

必须配置项：site_name

每个 MkDocs 项目必须包含 site_name 配置项，它定义了网站的主标题：

site_name: 我的技术文档

这个值会被传递给主题模板作为 site_name 上下文变量。

网站元信息配置

site_url

设置网站的规范 URL，会在每个页面的 <head> 部分添加 canonical 链接标签：

site_url: https://example.com/docs/

当使用 mkdocs serve 时，服务器会根据这个 URL 的路径部分来模拟远程布局。

site_description 和 site_author

这两个配置项会添加 meta 标签到 HTML 头部：

site_description: 这是关于Python开发的详细文档
site_author: 张三

copyright

copyright: "© 2023 我的公司"

版本控制集成

仓库链接配置

repo_url: https://example.com/project/repo
repo_name: 项目仓库

设置后会在每个页面显示指向仓库的链接。

编辑链接配置

edit_uri 允许用户直接从文档页面跳转到源文件进行编辑：

edit_uri: blob/main/docs/

对于 GitHub/GitLab 仓库，MkDocs 会自动设置合理的默认值。如果需要自定义行为，可以使用更灵活的 edit_uri_template：

edit_uri_template: 'blob/main/docs/{path}'

支持以下变量：

{path}: 文件路径（如 foo/bar.md）
{path_noext}: 不带扩展名的路径
{path!q}: URL 编码后的路径

文档结构配置

导航菜单 (nav)

定义网站导航结构的最重要配置：

nav:
  - 首页: index.md
  - 用户指南:
    - 安装: guide/installation.md
    - 使用: guide/usage.md
  - API参考: api.md
  - 问题跟踪: https://example.com/issues/

路径相对于 docs_dir，支持嵌套结构和外部链接。

文件排除规则

exclude_docs

定义不包含在构建中的文件模式：

exclude_docs: |
  *.py
  /private/
  !/private/example.md  # 例外

遵循 .gitignore 格式，默认排除点文件和 templates 目录。

draft_docs (1.6+)

定义草稿文件，这些文件在开发服务器可见但不会构建：

draft_docs: |
  drafts/
  *_unpublished.md

not_in_nav

明确声明不包含在导航中的文件，避免警告：

not_in_nav: |
  /internal.md

验证配置 (1.5+)

控制链接验证的严格程度：

validation:
  nav:
    omitted_files: warn
    not_found: error
  links:
    absolute_links: relative_to_docs
    anchors: warn

绝对链接处理 (1.6+)

新增 relative_to_docs 选项，将 / 开头的链接解析为相对于 docs 目录：

validation:
  links:
    absolute_links: relative_to_docs

这样 /guide/usage.md 会被正确解析并验证。

主题配置

theme:
  name: mkdocs
  custom_dir: my_theme_overrides/
  features:
    - navigation.tabs

支持的主题包括 mkdocs、readthedocs 等，可以通过 custom_dir 覆盖主题文件。

构建目录配置

docs_dir: src
site_dir: public
strict: true

docs_dir: 源文档目录（默认 docs）
site_dir: 输出目录（默认 site）
strict: 严格模式（验证错误时构建失败）

高级功能

多语言支持

theme:
  locale: zh

插件配置

plugins:
  - search
  - markdownextradata:
      data: data.yml

最佳实践建议

始终设置 site_name
使用 nav 明确控制导航结构
启用链接验证（特别是生产环境）
考虑使用 relative_to_docs 简化跨目录链接
利用 draft_docs 管理工作流程
通过 validation 配置尽早发现问题

通过合理配置这些选项，您可以构建出结构清晰、易于维护的专业文档网站。MkDocs 的配置系统既简单又强大，能够满足从个人项目到企业级文档的各种需求。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考