关于MkDocs，如果不了解的可以先翻官网，主题我选择的是MkDocs-Material，传送门：
https://www.mkdocs.org/
https://squidfunk.github.io/mkdocs-material/
另外推荐一个MkDocs实例（中文）供参考，上面也提供了很多MkDocs知识点和最佳实践：
https://cyent.github.io/markdown-with-mkdocs-material/
总之，MkDocs是非常适合用来做教程或者文档主题的纯静态网站系统，将Markdown格式编写的md文件通过python转换为html页面，然后部署到GitHub或者自己的站点（nginx部署）。一条命令就可以实现，非常简单、易用。页面效果如下，很Google风不是么？
OK，让我们回到正题，这里讲的两个模块是上面网站或者官网没有提及的，本文讲详细讲解下。
一、MkDocs 网站访问统计
其实阿里云和腾讯云都分别有自己的客服帮助文档，这种文档本质上和Mkdocs是差不多的，当然加入了不少他们自己的广告和导航之类的，但是也都是纯静态页面，页面很流畅，舒服。一天我在翻阅腾讯云开发者帮助文档时看到它对每篇文章做了文章PV统计，就想到如果时Mkdocs要如何实现呢？
1. 网站访问统计方法选择
之前也了解一些PV统计，配合搜索引擎，最终决定采用不蒜子的方案，好集成也好用。
不蒜子的官网：http://busuanzi.ibruce.info/
它的集成也很简单，只需要两行代码即集成了：
<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>
<span id="busuanzi_container_site_pv">本站总访问量<span id="busuanzi_value_site_pv"></span>次</span>
上面是网站总PV，如果需要页面的PV或者UV则稍微调整下：
<span id="busuanzi_container_page_pv">本文总阅读量<span id="busuanzi_value_page_pv"></span>次</span>
<span id="busuanzi_container_site_uv">本站访客数<span id="busuanzi_value_site_uv"></span>人次</span>
也就是说，我只需要导入busuanzi.pure.min.js并在html页面当中添加一个span标签即可，非常简单
那么在MkDocs里面要如何导入呢？
2. 导入js文件
首先是js文件，通过编辑Mkdocs的模板yaml文件即可实现：
# mkdocs.yaml
extra_javascript:
- '//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js'
当然如果你想通过本地加载该js也是可以的，就提前下载好js放入本地，再把上面地址改为本地路径即可：
# mkdocs.yaml
extra_javascript:
- 'assets/js/busuanzi.pure.mini.js'
3. 插入展示html代码
接下来就是要在页面当中哪个位置展示PV量比较合适？我优先选择的是直接放到文章末尾。
方案一：查找mkdocs模板base.html文件article结束标签并插入html代码
可以在mkdocs build之前查找base.html模板文件当中的article结束标签并插入html代码，比如你写个shell脚本在mkdocs build之前加入如下代码（注意调整base文件的路径为你的实际路径）：
# build.sh
sed -i 's/<\/article>/<hr><span id="busuanzi_container_page_pv"><font size="3" color="grey">本文总阅读量<span id="busuanzi_value_page_pv"><\/span>次<\/font><\/span><br\/><\/article>/g' mkdocs-material/material/base.html
mkdocs build
如果你是通过docker来构建镜像的则在dockerfile里面RUN上面这条命令，示例：
# Dockerfile
RUN sed -i 's/<\/article>/<hr><span id="busuanzi_container_page_pv"><font size="3" color="grey">本文总阅读量<span id="busuanzi_value_page_pv"><\/span>次<\/font><\/span><br\/><\/article>/g' mkdocs-material/material/base.html
方案二：通过Nginx的ngx_http_sub_module模块实现查找article结束标签并插入html代码
如果不想修改material的模板文件，那么还有一个更简单对代码没有侵入性的方式，那就是通过nginx的ngx_http_sub_module模块来达到修改代码的目的。
首先你要确保你的nginx是有开启ngx_http_sub_module模块的，可以通过nginx -v来确认。没有的话需要重新安装并开启。
然后我们来修改nginx的配置文件：/etc/nginx/conf.d/default.conf
在对应的 server > location 上下文中，添加 sub_filter 指令。这里使用了变量 $injected 保存了脚本地址，对response中有 body 标签的地方修改插入。
location / {
# ... 前面原有的代码省略
set $injected '<span id="busuanzi_container_page_pv"><font size="3" color="grey">本文总阅读量<span id="busuanzi_value_page_pv"></span>次</font></span>';
sub_filter '</article>' '<hr>${injected}<br/></article>';
sub_filter_types *;
sub_filter_once on;
}
其中的代码含义如下：
#sub_filter 一行代码前面是需要替换的内容，后面单引号内是替换成的内容。
#sub_filter_once 意思是只查找并替换一次。on是开启此功能，off是关闭——默认值是on。
#sub_filter_types 一行意思是选定查找替换文件类型为文本型。也可以不加此行，因为默认只查找text/html文件。
#sub_filter模块可以用在http, server, location模块中。主要作用就是查找替换文件字符。
4. 效果
上面两个方案都是我们把所有页面当中在article文章标签结束之前插入了不蒜子的span用来显示文章阅读量，效果如下：
如果想要放到其它地方，比如标题处，同样按照上述方法，只需要按照上述方案进行改造即可，比如说放在标题栏附近，那么修改base.html模板：
# build.sh
sed -i 's/{\% if page.edit_url \%}/<div style="float:right"><span id="busuanzi_container_page_pv"><font size="2" color="grey">本文总阅读量<span id="busuanzi_value_page_pv"><\/span>次<\/font><\/span><\/div>{\% if page.edit_url \%}/g' mkdocs-material/material/base.html
mkdocs build
最终效果如下图所示，这样看效果感觉更好哈，看个人喜好吧：
5. 举一反三 google-fonts本地加载
另外举一反三，针对Mkdocs里面使用Google字体加载慢的问题，也可以采用此办法来加快js的加载，把js和字体库下载到本地，然后可以通过sed命令把原来的Google字体库链接和js替换掉或者注释掉，再通过配置文件将js加载进来，字体库的话则可以通过COPY命令拷贝到nginx服务器上。
二、MkDocs添加评论系统（使用livere来必应）
我们站点是纯静态网页，那么如果想要获取用户的反馈，比如用户评论，那么要怎么实现呢？
可以结合第三方的用户评论系统，不过大多数都是墙外的，国内加载实在太慢，来必应livere是韩国最大的社交评论系统，关键是在国内整合了qq/微博/微信/百度/人人/豆瓣等国内的用户系统，非常方便。
下面我们再来看如何在文章末尾嵌入评论系统，实现的效果先看下：
1. 注册来必应
来比力官网：http://livere.com
注册好后，点击管理页面，在代码管理中找到你自己的专属安装代码。比如我的：
<!-- 来必力City版安装代码 -->
<div id="lv-container" data-id="city" data-uid="MTA***********************Mw==">
<script type="text/javascript">
(function(d, s) {
var j, e = d.getElementsByTagName(s)[0];
if (typeof LivereTower === 'function') { return; }
j = d.createElement(s);
j.src = 'https://cdn-city.livere.com/js/embed.dist.js';
j.async = true;
e.parentNode.insertBefore(j, e);
})(document, 'script');
</script>
<noscript> 为正常使用来必力评论功能请激活JavaScript</noscript>
</div>
<!-- City版安装代码已完成 -->
2. 修改mkdocs.yaml配置文件
extra:
disqus: 'something'
3. 更新disqus.html文件
根据你的构建方法手工更新disqus.html文件，文件路径，具体看你python的安装路径：
...\Python\Python36\Lib\site-packages\material\partials\integrations\disqus.html
总之要更新它，原来是：
{#-
This file was automatically generated - do not edit
-#}
{% set disqus = config.extra.disqus %}
{% if page and page.meta and page.meta.disqus is string %}
{% set disqus = page.meta.disqus %}
{% endif %}
{% if not page.is_homepage and disqus %}
<h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
<div id="disqus_thread"></div>
<script>
var disqus_config = function () {
this.page.url = "{{ page.canonical_url }}";
this.page.identifier =
"{{ page.canonical_url | replace(config.site_url, "") }}";
};
(function() {
var d = document, s = d.createElement("script");
s.src = "//{{ disqus }}.disqus.com/embed.js";
s.setAttribute("data-timestamp", +new Date());
(d.head || d.body).appendChild(s);
})();
</script>
{% endif %}
更换为来必应的安装代码：
{#-
This file was automatically generated - do not edit
-#}
{% set disqus = config.extra.disqus %}
{% if page and page.meta and page.meta.disqus is string %}
{% set disqus = page.meta.disqus %}
{% endif %}
{% if not page.is_homepage and disqus %}
<div id="lv-container" data-id="city" data-uid="MT******************yMw==">
<script type="text/javascript">
(function(d, s) {
var j, e = d.getElementsByTagName(s)[0];
if (typeof LivereTower === 'function') { return; }
j = d.createElement(s);
j.src = 'https://cdn-city.livere.com/js/embed.dist.js';
j.async = true;
e.parentNode.insertBefore(j, e);
})(document, 'script');
</script>
<noscript> 为正常使用来必力评论功能请激活JavaScript</noscript>
</div>
{% endif %}
如果你是如上文中提到的通过shell脚本构建你的网站，那么只需要在上述html代码另存为disqus.html，然后在shell命令中mkdocs build之前替换掉它（注意具体的路径）：
# build.sh
cp ./static/disqus.html /usr/local/lib/python3.6/site-packages/material/partials/integrations/disqus.html
mkdocs build
如果你是docker构建的话则在Dockerfile里面替换掉它（注意具体的路径）：
COPY ./static/disqus.html /usr/local/lib/python3.6/site-packages/material/partials/integrations/disqus.html
然后就可以在页面上验证啦，十分方便！
关于整合livere参考项目：OI-wiki
扫一扫
1062
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
