Home
-
导航栏
- 简洁美观 ，功能多元化，小白配置
- 基于
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
-
Mkdocs教程(必看)
-
关于
4.解决mkdocs serve 后127.0.0.1:8000无法自动刷新的问题
问题是 click 8.3.x 版本有 bug，导致 mkdocs 的 livereload 文件监控失效。 解决方法：降级 click 到 8.2.1 原贴： 不过目前 https://github.com/ProperDocs 作为新的mkdocs延续下去了，mkdocs serve 后127.0.0.1:8000无法自动刷新的问题已经解决
2026网站更新记录
2026-03-30
优化网站流畅度（玄学） 写点东西，修修bug
2026-03-02
优化网站流畅度（玄学） 改进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 年年中，他们在代码库中的活动就完全停止了。
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账号(有手就行)
2.Mkdocs配置说明(mkdocs.yml)
官方文件：Changing the colors - Material for MkDocs 建议详细学习一下上面的官方网站↑↑↑ 我把我目前的配置文件mkdocs.yml代码写在下面👇🏻 从头开始分析 无须多言 theme部分 顶部颜色 primary后面是网站顶部栏目的颜色（也用于标题、边栏、文本链接和其他几个组件） 目前支持下面几个颜色： 明暗主题按钮
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
友链
失联人员 独立博客(不要求独立域名)，https，访问流畅 原创内容为主，原创内容3篇以上 处于活跃状态，有一定的更新频率 建站一个月以上 未添加友链或申请未通过，评论留言会被隐藏。 本站已经加入十年之约： 友链格式示例/本站信息: 推荐在评论区发送这种格式，号的需要填写自己的信息
添加评论系统(giscus为例)
官方文档：Adding a comment system 这里我同样推荐giscus 利用 GitHub Discussions 实现的评论系统，让访客借助 GitHub 在你的网站上留下评论和反应吧！本项目深受 utterances 的启发。 开源。🌏 无跟踪，无广告，永久免费。📡 🚫 无需数据库。所有数据均储存在 GitHub Discussions 中。:octocat: 支持自定义主题！🌗 支持多种语言。🌐 高可配置性。🔧 自动从 GitHub 拉取新评论与编辑。🔃
添加404页面
首先在mkdocs.yml文件中添加customdir: docs/overrides文件下新建404.html 树状结构如下: 404公益页面 404骰子页面 目前更换了新的404页面：
添加Mkdocs博客
博客效果展示：博客 官方文档：Built-in blog plugin 与所有内置插件一样，博客插件的入门非常简单。只需将以下行添加到mkdocs.yml 然后在/docs/blog/posts下写md文件即可（无需再mkdocs.yml配置，如没有posts文件夹，新建一个即可） 插件会自动创建所需的目录结构。如果不存在，插件会创建： 在mkdocs.yml的nav部分这样写： 如果您的mkdocs.yml中已经定义了nav结构，需要启用navigation.indexes功能才能正确显示博客： 然后在nav部分添加博客： 元标签参考（每个博客文章必须包含date字段）： 作者信息在docs/blog/.authors.yml里配置（没有.authors.yml新建即可）