MkDocs 配置说明

预计阅读时长 : 10 分钟

这套个人写作工具组合，后端基于 Material for MkDocs ⧉ ，定制化的时候使用了付费的 insider ⧉ 版本，并增加了许多增强插件。

而前端编辑器则基于 Cursor ⧉，充分利用其 AI 辅助功能，并配置了多个功能强化的插件，以及自动化的部署流程，打造了最顺手的写作体验。

单项目配置

Mkdocs 配置的核心是 mkdocs.yml 文件，其定义了网站的结构、功能、样式等，是整个网站的灵魂。

为了更清晰的进行网站配置，在实践中将整个配置文件拆分成了多个部分，方便根据需要分别进行配置。

站点设置

站点设置主要配置了网站的名称、描述、版权、仓库地址等，这些配置了之后，在生成网站的时候，主要会影响网站的标题、描述、版权等固定信息。

导航设置

MkDocs 默认的站点导航信息会放在 mkdocs.yml 文件中。在实践中，使用了 mkdocs-literate-nav ⧉ 插件，可以将导航配置拆分到单独的 SUMMARY.md 文件中。这样在配置导航的时候，只需要修改 SUMMARY.md 文件即可，而不用去修改 mkdocs.yml 文件。

尤其是在需要将一个大的项目使用 Project ⧉ 插件拆分为多个子项目的场景下，使用单独的 SUMMARY.md 文件来管理各个子项目的导航，可以大大提高配置的复用性。

路径问题

在配置 site_url 的时候，需要注意的是，site_url 如果在域名后添加了子目录，则最终生成的所有链接也会带上这个子目录的路径。

主题设置

在主题设置中，主要配置了网站的样式、图标、字体、颜色等。

字体加载问题

需要特别注意的是，如果站点主要是在国内访问，则最好是关闭 font 选项，否则网站加载会非常慢。

此外，Material 主题的各项独有功能配置，也都是在这个部分中的 features 选项中进行配置。

插件配置

在插件配置中，主要配置了站点可用的插件，这些插件主要会影响网站的各项功能。

示例 mkdocs.yml 文件中的插件列表，已经在每一项后面简单标注了其作用，他们都是在长期的实践中，不断迭代出来的实用型插件，可以根据自己的需要进行选用。

需要注意的一点是，search 插件需要作为第一个插件进行配置，否则会导致初始化的时候报错。

Markdown 配置

Markdown 配置主要配置了 Markdown 语法的解析样式。除了最基础的语法外，还使用数学公式、代码块、表格、流程图、思维导图等各种各样的插件进行了大幅增强。

横向对比来看，市面上没有任何一个类似的写作工具，能够支持 加强语法 中无比全面的样式，尤其是在代码块、思维导图、时间轴等方面，可以说是全网独一份了。

资源配置

资源配置主要配置了网站会使用的静态资源，包括 CSS 和 JavaScript 文件，这些资源会提升网站的样式和功能。

这里特别说明一下， MkDocs 中默认是推荐使用尽可能调用外部资源的方式，这样实现外部资源的及时更新。但在中国的实际网络环境下，一些外部资源会因为你懂的原因经常加载失败。所以，在实践中启用了Privacy ⧉ 插件，将所有资源下载后放置到本地进行调用，这样就可以保证在任何网络环境下，都能正常加载。

其他配置

其他配置主要配置了网站的附加功能，包括标签和状态的图标、数据分析、社交媒体等。

多项目配置

为了更好的管理大型项目，可以选择使用 Project ⧉ 插件，将项目拆分为多个子项目，每个子项目都有自己单独的导航、插件、资源等配置。

在进行多项目配置的时候，需要注意的一点是，projects 插件的配置必须放到主项目的 mkdocs.yml 文件中，并指定子项目的路径到 projects_dir 属性中。

项目设置

通过实际测试，最佳的配置实践是在主项目的 mkdocs.yml 文件中，只保留最基本的配置项，而将大多数的配置项都移动到子项目的 mkdocs.yml 文件中。

最佳实践

这样做的主要原因是，子项目的配置只能部分而不能全部继承主项目的配置，这导致如果依赖继承关系拆分配置文件，两者的内容都会变得非常零碎且没有逻辑。

项目模板

如果要配置多个子项目，会发现每个子项目都需要单独配置一遍插件、资源等，这个过程非常繁琐。

因此，可以创建一个项目模板，这样在创建新子项目的时候，就可以直接继承模板中的配置，从而简化配置流程。

在 Cursor 中，可以使用 Folder Templates ⧉ 插件，来创建项目模板并快速创建新子项目。