docsify，专为喜欢折腾的你。

使用体验

五一回家只带了公司笔记本，没什么娱乐软件，所以闲时刷了下 Github，发现一个 TIL(things I learn) 项目挺好的，于是 clone 下来做了一个自己的项目，这是我的 TIL 记录。

TIL 本意是记录自己学到的知识点。实际工作中会经常遇到问题并解决问题，长期以来并没有刻意记录，有些问题单凭记忆会在一段时间后忘记。

原项目中是依赖 Gitbook 做的文本渲染，按照我几年前的使用经历来看，Gitbook不算好用，并且在国内访问速度堪忧，所以我在这里选择了 docsify。

docsify 是一个类似 Gitbook 将 Markdown 文件选染成 HTML 页面的工具。当然也有一定差别，Gitbook 是提前编译成 HTML 静态页面，而 docsify 是请求时渲染。在使用上来看，docsify 的速度更快，也更简单一些，可自定义的配置非常多，适用于喜欢自己动手的开发者。
docsify 功能非常丰富，不过基本界面样式比较简单。

值得吐槽的是右上角repo角标太大了，和navbar菜单并在一起太丑陋了。

image-20210509161029217

其他的一些插件，比如 「edit on github」 与 「字数插件」 会将正文内容往下挤，也很别扭。

image-20210509161238605

官方文档里没有浅色模式与深色模式的灵活适配，只单一支持了浅色或深色主题，也就是说只能选择一种。

如果想同时支持浅色和深色，目前有两个方法：

  1. 有一个第三方主题插件，docsify darklight theme，安装即用，提供一个按钮手动切换，不过问题是仍然是按钮将正文内容往下挤压。我添加了一段JS方法，强制将按钮移到左侧sidebar。
  2. 自定义css，支持跟随系统深色模式，自动切换。实现方式类似我的blog，目前还没有时间开发。

开始构建

首先需要本地具备 node 和 npm 环境，选择最新的稳定版本即可。

安装 docsify-cli：

1
npm install -g docsify-cli

创建 Git 仓库，并且初始化 docsify：

1
2
mkdir docsify-demo && cd docsify-demo
docsify init docs

这之后会自动创建出 docs 目录，其中会有一个 index.html 文件。

可以本地预览了：

1
docsify serve docs

然后，可以编辑 index.html：

1
2
3
4
5
6
7
8
window.$docsify = {
	name: 'Things I Learn',
	loadSidebar: true,
	loadNavbar: true,
	search: 'auto',
	// 下面按照文档添加各种插件即可
	...
}

可以在 docs 目录下创建这些文件：

  • 一个空的 .nojekyll 文件，用于阻止 Github Page 忽略下划线开头的文件；
  • _sidebar.md 文件，自定义左侧边栏目录；
  • _navbar.md 文件，自定义右上角菜单栏。

可以安装 docsify-tool 依赖，我只用它来自动生成 _sidebar.md 内容：

1
2
npm i -g docsify-tools
docsify-auto-sidebar -d docs

docsify-auto-sidebar 会将指定 docs 目录下所有 Markdown 文件识别为目录内容，所以会将 _navbar.md 也将到目录里，我写了一个 Git pre-commit hook 来阻止这个动作。

在项目根目录，vim .git/hooks/pre-commit，填入：

1
2
3
4
5
docsify-auto-sidebar -d docs
# 替换，二选一
sed -i "" "/_navbar/d" docs/_sidebar.md # mac
sed -i "/_navbar/d" docs/_sidebar.md # linux
git add .

评论系统

docsify 支持 Disqus 和 Gitalk 两种评论系统。Disqus 在国内不太好用，所以我选择试试 Gitalk。

按照 docsify 的文档，很简单的使用上了 Gitalk 评论，但是在使用中发现满满的都是坑。

我这里主要问题是某些文章加载评论时报错 Error: Validation Failed。

Gitalk 依托于 Github issue 存在，并且使用 issue label 和文章一一关联，issue label 有个限制是字符串长度需不超过 50。

然而 docsify 默认和 Gitalk 的集成，创建 issue 时使用的 label 是当前页面的 location.href，也即是 URL 全文，这也太容易超过 50 了吧🥲。

在 Gitalk 文档中，也有说明 id 属性，默认使用 location.href：

id String

Default: location.href.

页面的唯一标识。长度必须小于50。

在网上找到的解决方案，是手动设置 id 属性，对 href 做一次 md5，固定到 32 位。看起来很不错，引用了一个 md5 库之后，很简单搞定了。然而实际应用发现 docsify 切换页面时，路由经常没有自动刷新，导致各种奇奇怪怪的gitalk初始化问题，然后创建出的 issue 烂七八糟，而且经常在 A 页面写的评论在 B 页面可以加载出来。我猜测还是路由回调的问题，但我看不懂源码，没法解决。

然后在 Github 找了一些使用 docsify 写的项目文档，发现一个 l-hammer/You-need-to-know-css，效果很好并且评论没有问题。

读了这个项目的实现，发现没有依赖 docsify 对 Gitalk 的集成，直接引入的 Gitalk 依赖，并且在路由回调中初始化 gitalk 实例。

大概实现如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
gitalkConfig = {
    clientID: "xxx", // your github oauth app client id
    clientSecret: "xxx", //your github oauth app client screct key
    repo: "til", //your github repo name
    owner: "fakeYanss", //your github user name
    admin: ["fakeYanss"], //your gitalk administrators
    perPage: 20,
    language: "en",
    labels: ["Gitalk"],
    distractionFreeMode: false
};
plugins: [
    function (hook, vm) {
        hook.doneEach(function () {
            var label, domObj, main, divEle, gitalk;
            label = vm.route.path.split("/").pop();
            domObj = Docsify.dom;
            main = domObj.getNode("#main");

            /**
             * render gittalk
             */
            if (vm.route.path.includes("zh-cn")) {
                gitalkConfig.language = "zh-CN";
            }
            Array.apply(
                null,
                document.querySelectorAll("div.gitalk-container")
            ).forEach(function (ele) {
                ele.remove();
            });
            divEle = domObj.create("div");
            divEle.id = "gitalk-container-" + label;
            divEle.className = "gitalk-container";
            divEle.style = "width: " + main.clientWidth + "px; margin: 0 auto 20px;";
            domObj.appendTo(domObj.find(".content"), divEle);
            gitalk = new Gitalk(
                Object.assign(gitalkConfig, {
                    id: !label ? "home" : label
                })
            );
            gitalk.render("gitalk-container-" + label);
        })
    }
]

最后效果是这样，label 使用的是 location.hash 的尾部按 / 分割后的最后一段内容，其实就是每个 Markdown 文件名，到这一步已经很容易控制不超过 50 位长度了。

image-20210509172714680

主题定制

darklight

使用docsify darklight theme，按照文档说明，非常简单。

在 index.html 头部添加：

1
2
3
4
5
6
<link 
    rel="stylesheet"
    href="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/style.min.css"
    title="docsify-darklight-theme"
    type="text/css"
/>

在底部添加：

1
2
3
4
<script 
    src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"
    type="text/javascript">
</script>

如果对默认的按钮展示位置满意，那可以到此结束了，下面是我的改动，将按钮移动到左侧边栏：

image-20210509163856711

下载 darklight 的 Javascript 源码，放到项目里，可以命名为 theme.js，移除远程引用，添加本地引用：

1
<script src="theme.js"></script>

然后修改 theme.js 的一处方法，这里的 afterEach 是 docsify 路由变化完成后的回调函数，主题原生的写法就是在 e 前面简单添加一个 div 块，这也是按钮将正文内容向下挤压的原因。添加 else 分支是因为这块代码在每次路由变化后都会执行，我们需要让它只在第一次加载页面时创建按钮 div。

1
2
3
4
5
6
7
e.afterEach((function (e, o) {
    if (document.getElementById('docsify-darklight-theme') == null) {
        o(e = '<div id="docsify-darklight-theme"><p>.</p></div>' + e)
    } else {
        o(e)
    }
}))

源码是编译过的，为了避免找不到在哪，这里是我改过的 theme.js 下载地址。

由于没有深入阅读 docsify 的主要源码，不确定这处方法怎么直接改动，所以在外面另外写了一处脚本作为后置处理，将按钮 append 到侧边栏的 DOM 下。在 index.html 中，添加一段 script：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<script>
    function move() {
      document.getElementsByClassName('sidebar')[0].setAttribute('id', 'sidebar-full')
      document.getElementById('sidebar-full').appendChild(document.getElementById('docsify-darklight-theme'))
      var button = document.getElementById('docsify-darklight-theme')
      button.style.position = 'fixed'
      button.style.left = '10px'
      button.style.bottom = '58px'
      button.style.top = 'auto'
      button.style.width = '18px'
      button.style.height = '18px'
    }
    var refreshId = setInterval(function () {
      if (null != document.getElementById('docsify-darklight-theme')) {
        move();
        clearInterval(refreshId);
      }
    }, 100);
</script>

如果觉得侧边栏问题太挤，可以再调整下样式：

1
2
3
4
5
6
7
8
9
10
<style>
.sidebar-nav ul li {
    margin-left: 25px;
}

.sidebar-nav {
    line-height: 1.5em !important;
    padding-bottom: 76px;
}
</style>

prefers-color-scheme

prefers-color-scheme 是 CSS media feature 对黑暗模式的支持，详细文档在此。

按照我的博客的做法，只需设计下黑暗模式的背景颜色、字体颜色、代码块颜色、超链接颜色，基本效果就有了。

细节待开发…


#docsify
2021 年 05 月 09 日