MkDocs 使用

2026-04-172026-07-07

mkdocs-document-dates插件

Front Matter 设置

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

GoatCounter 阅读量统计

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

GoatCounter 账号设置

注册 GoatCounter 时：

• Account name：jambitx
• Site domain：当前没有自定义域名时先填 jambitx11.github.io
• 后台需要打开允许 visitor counter 在网页上公开显示访问数的选项

如果以后换成自己的域名，例如 blog.jambitx.top，再去 GoatCounter 后台把站点 domain 改掉，或者新增一个 site。

MkDocs 接入方式

因为站点启用了 navigation.instant，页面切换时不会完整刷新，所以不能只依赖 GoatCounter 默认的页面加载统计。当前接入方式是：

1. 在 docs/javascripts/pageviews.js 中设置：

const goatCounterEndpoint = "https://jambitx.goatcounter.com/count";

1. 设置：

window.goatcounter.no_onload = true;

这样可以关闭 GoatCounter 的默认 onload 统计，避免和手动统计重复。

1. 在 Material 的 document$ 页面切换事件中手动调用：

window.goatcounter.count({
  path: window.location.pathname,
  title: document.title,
  event: false,
});

1. 再从 GoatCounter 的 counter JSON 接口读取当前页面访问数，并插入正文标题下方。

样式写在：

docs/styles/pageviews.css

mkdocs.yml 中挂载：

extra_css:
  - styles/pageviews.css

extra_javascript:
  - javascripts/pageviews.js

注意

• 如果 GoatCounter 的 account name 不是 jambitx，只需要改 docs/javascripts/pageviews.js 里的 goatCounterEndpoint。
• 本地预览时如果 GoatCounter 还没允许公开 visitor counter，页面会显示“暂不可见”，但不影响站点构建。
• 统计路径使用 window.location.pathname，以后从 jambitx11.github.io 换到自定义域名时，只要页面路径不变，统计逻辑不用改。