MkDocs 使用

2026-04-172026-07-07

mkdocs 使用文档网站

`mkdocs-document-dates` 插件

Front Matter 设置

---
created: xxxx-xx-xx
updated: 
cover:
---

不蒜子阅读量统计

想给静态站点显示“阅读 N 次”，核心是：MkDocs 只负责生成页面，访问次数必须交给外部服务或后端保存。这里改用不蒜子做前台阅读量展示，不需要自己买服务器。

不蒜子的页面访问量

不蒜子会自动识别一些固定 ID，并把统计数填进去：

<span id="busuanzi_container_page_pv">
  <span id="busuanzi_value_page_pv"></span>
</span>

其中：

busuanzi_value_page_pv：当前页面 PV
busuanzi_value_site_pv：全站 PV
busuanzi_value_site_uv：全站 UV

MkDocs 接入方式

因为站点启用了 navigation.instant，页面切换时不会完整刷新，所以不能只在首次页面加载时引入不蒜子脚本。当前接入方式是：

docs/javascripts/pageviews.js 先在正文里插入不蒜子需要的 DOM：

<span id="busuanzi_container_page_pv" class="pageviews dd-item">
  <span class="material-icons pageviews__icon">visibility</span>
  <span id="busuanzi_value_page_pv" class="pageviews__count">...</span>
  <span class="pageviews__unit">次</span>
</span>

为了让阅读量和创建/更新时间保持在同一排，脚本会优先查找日期插件生成的容器：

const dateRow = article.querySelector(".document-dates-plugin .dd-left");

如果找到了，就把阅读量组件追加进去；如果当前页面没有日期插件，再退回插入标题下方。

然后动态加载不蒜子脚本：

const scriptSrc = "https://busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js";

在 Material 的 document$ 页面切换事件里重新加载不蒜子脚本：

document$.subscribe(setupPageviews);

样式写在：

docs/styles/pageviews.css

用 front matter 控制是否显示

如果某个页面不想显示阅读量，在 Markdown 文件顶部的 front matter 里加：

---
pageviews: false
---

比如首页或者某个板块索引页可以这样写：

---
title: Home
pageviews: false
hide:
  - toc
  - footer
---

实现方式是 docs/overrides/main.html 把 MkDocs 的 page.meta.pageviews 输出成一个隐藏配置：

<span class="pageviews-config" data-pageviews="false" hidden></span>

然后 docs/javascripts/pageviews.js 读取这个配置。如果值是 false，就隐藏阅读量，也不加载不蒜子脚本；如果没有设置，默认显示。

这个隐藏配置放在 main.html 的 site_nav block 里，而不是 content block。原因是 Material 的博客插件会用 blog.html 覆盖 container block，博客索引页不一定会走普通页面的 content block；放在 site_nav block 可以让普通页面和博客索引页都拿到同一个 front matter 配置。

注意

不蒜子没有后台，优点是接入简单、前台数字变化比较灵敏；缺点是数据不可控。
本地 mkdocs serve 不加载不蒜子，避免把 localhost 计入统计。
如果访问者的广告拦截插件拦截了不蒜子脚本，阅读量可能不会显示。

代码注释功能

在 mkdocs.yml 的 feature 配置中打开

- content.code.annotate

然后在文档中这样写（注意有序列表空且只能空一行）

```yaml
theme:
  name: materialx # (1)
```

1. 这里指定使用 MaterialX 主题。

theme:
  name: materialx # (1)

这里指定使用 MaterialX 主题。

就能实现代码嵌入注释，非常好用

联动整个网站中的同名选项卡

pytorchtensorflow

pytorch

tensorflow

很像 d2l 里面的那个