Home

🎉 Zensical中文教程 —— 最新zensical中文教程 了解更多 →
✈️ 好用机场 —— 季付低至22元|70+国家线路 千兆带宽|支持流媒体|8折优惠码：VPN07
✨ 欢迎了解 mkdocs-materialx —— 新版MkDocs主题 仓库地址｜ Wechat 群组
最好的MkDocs中文教程

  • 导航栏

    image

    • 简洁美观 ，功能多元化，小白配置
    • 基于Material for MkDocs美化
    • 如遇页面卡顿，请使用科学上网
    • 𝕙𝕒𝕧𝕖 𝕒 𝕘𝕠𝕠𝕕 𝕥𝕚𝕞𝕖 !

    请在上方标签选择分类/左侧目录选择文章

    请点击左上角图标选择分类和文章

不同于市面上过时的MkDocs教程，本站提供了最详细最便捷最前沿的MkDocs中文文字/视频教程，与官方发布的教程版本同步。包含了MkDocs的安装、配置、主题美化、插件使用等内容。无论你是初学者还是有经验的用户，都能在这里找到你需要的帮助。我们还提供了示例和实用的技巧，帮助你更好地使用MkDocs。𝓳𝓾𝓼𝓽 𝓮𝓷𝓳𝓸𝔂 𝓲𝓽～

重要提醒

Mkdocs for material已经进入维护状态，materialX作为mkdocs的延续被广泛使用，本站作为mkdocs教程站迁移至materialX主题。 Zensical是 mkdocs for material原作者的延续，提供了更丰富的功能和更现代的UI设计，可以考虑迁移至Zensical主题，我不再更新mkdocs for material教程。

2026.3 目前 https://github.com/ProperDocs 作为新的mkdocs延续下去了，我只能说mkdocs圈真乱,本UP主已经全面拥抱Zensical了。吃瓜请去这里和MKDocs 的缓慢崩溃。所以如果使用mkdocs，我首先还是推荐materialX

4.解决mkdocs serve 后127.0.0.1:8000无法自动刷新的问题
问题是 click 8.3.x 版本有 bug，导致 mkdocs 的 livereload 文件监控失效。 解决方法：降级 click 到 8.2.1 原贴： 不过目前 作为新的mkdocs延续下去了，mkdocs serve 后127.0.0.1:8000无法自动刷新的问题已经解决
hourglass_top阅读时长 1 分钟
2026网站更新记录

2026-05-22

优化网站流畅度（玄学） 改进mkdocs教程，增加更多示例

2026-03-30

优化网站流畅度（玄学） 写点东西，修修bug

2026-03-02

优化网站流畅度（玄学） 改进mkdocs教程，增加更多示例

hourglass_top阅读时长 2 分钟
添加阅读信息统计
1. 基础配置 步骤1 创建readingtime.py 步骤2 把readingtime.py放到docs/overrides/hooks目录下，然后在mkdocs.yml中添加： 步骤3 配置MkDocs主题以及覆写路径customdir 到这里检查下目录树状图: 步骤4 2. 效果展示
hourglass_top阅读时长 6 分钟
Mkdocs
添加相关推荐文章
步骤 mkdocs.yml中需要覆写文件夹overrides(没有的话新建一个) 在docs/overrides/hooks/下新建一个relatedposts.py文件即可，内容如下： 具体配置根据自己仓库情况自行修改 然后需要在 mkdocs.yml 中添加： 效果如下
hourglass_top阅读时长 8 分钟
Mkdocs
MKDocs 的缓慢崩溃
本文译者：shenweiyan 2026 年 3 月 9 日， MkDocs 的一位前维护者接管了 PyPI 代码库的控制权，并撤销了原作者的权限。原作者迅速作出回应： 然后他们提交了一份 PyPI 支持工单 以重新获得控制权，但在工单得到处理之前，问题就已得到了解决。 MkDocs 为超过 90,000 个 GitHub 项目提供文档支持，其中大多数项目都依赖于由 @squidfunk 开发的 Material for MkDocs 主题，该主题非常受欢迎，其获得的星标数甚至超过了 MkDocs 本身。 PyPI 被接管事件不过是更深层次问题的一个最为显眼的症状表现。如今，任何使用 Material for MkDocs 的人都会在终端中看到以下警告信息： MkDocs 项目已经超过 18 个月没有进行任何实质性的开发。Material for MkDocs 目前处于维护模式。而曾经两大主导工具携手共进的局面已不复存在，如今有多款工具竞相涌现，试图取而代之：如 ProperDocs、MaterialX（"新一代的 mkdocs-material"）以及 Zensical（"由 Material for MkDocs 开发者打造的现代化静态网站生成器"）。 我们怎么会走到这一步？要了解事情的全貌，我们需要稍微回顾一下过去 …… 2014年1月11日 - MkDocs 的诞生 2014 年 1 月 11 日，Mia Kimberly Christie（ @lovelydinosaur ）提交了第一个代码 ，也就是后来的 MkDocs，并附上了 "Hell yeah" 的消息。接下来的几个月里，提交数量激增。 这种活跃期并没有持续太久。到 2014 年年中，他们在代码库中的活动就完全停止了。
hourglass_top阅读时长 10 分钟
1.利用Mkdocs部署静态网页
Material for MkDocs官方网站: Material for MkDocs MkDocs官方文档: MkDocs MkDocs中文文档: MkDocs中文文档 推荐看下这个视频： :fontawesome-brands-bilibili: [How to set up Material for MkDocs] by @Wcowin – :octicons-clock-24: 10m – 用MKdocs构建一个博客网站. 一、准备工作 1.下载Github Desktop 2.有一个GitHub账号​​​​​​​(有手就行)
hourglass_top阅读时长 4 分钟
Mkdocs
2.Mkdocs配置说明(mkdocs.yml)
官方文件：Changing the colors - Material for MkDocs 建议详细学习一下上面的官方网站↑↑↑ 我把我目前的配置文件mkdocs.yml代码写在下面👇🏻 从头开始分析 无须多言 theme部分 顶部颜色 primary后面是网站顶部栏目的颜色（也用于标题、边栏、文本链接和其他几个组件） 目前支持下面几个颜色： 明暗主题按钮
hourglass_top阅读时长 13 分钟
Mkdocs
3.解决Github Pages部署mkdocs自定义域名失效的问题
解决方法 在/docs目录下创建一个名为CNAME的文件（无后缀），然后在里面填入你的域名（每行一个域名）： 或者子域名： 因为每次在 GitHub 仓库的 Settings > Pages > Custom domain 中添加域名后，GitHub 会在gh-pages分支自动生成一个 CNAME 文件。但是因为项目我们没有 pull 到本地，所以每次 push 之后 CNAME 信息被覆盖了。 1. CNAME文件必须放在docs/目录下，这样在构建时会自动复制到站点根目录 2. 确保在mkdocs.yml中设置了正确的siteurl： 3. 如果使用自定义域名，还需要在域名DNS设置中添加CNAME记录指向GitHub Pages
hourglass_top阅读时长 1 分钟
Mkdocs
友链
失联人员 独立博客(不要求独立域名)，https，访问流畅 原创内容为主，原创内容3篇以上 处于活跃状态，有一定的更新频率 建站一个月以上 未添加友链或申请未通过，评论留言会被隐藏。 本站已经加入十年之约： 友链格式示例/本站信息: 推荐在评论区发送这种格式，号的需要填写自己的信息
hourglass_top阅读时长 1 分钟
添加评论系统(giscus为例)
官方文档：Adding a comment system 这里我同样推荐giscus 利用 GitHub Discussions 实现的评论系统，让访客借助 GitHub 在你的网站上留下评论和反应吧！本项目深受 utterances 的启发。 开源。🌏 无跟踪，无广告，永久免费。📡 🚫 无需数据库。所有数据均储存在 GitHub Discussions 中。:octocat: 支持自定义主题！🌗 支持多种语言。🌐 高可配置性。🔧 自动从 GitHub 拉取新评论与编辑。🔃
hourglass_top阅读时长 3 分钟
Mkdocs