docsify 的使用

#软件使用

docsify 是一套简单的文档网站生成工具，不像其它静态博客会生成一堆文件，它的转换在运行时，所以比较清爽，只要一个 html 文件。

具体的操作看官网就行，下面记录一些在使用过程中不太容易记得及遇到的一些问题。

  1. 在标题后写 <!-- {docsify-ignore} --> 排除在侧边栏显示，在文档第一个标题后添加 <!-- {docsify-ignore-all} --> 可以忽略文档标题。

  2. 文件名后加内容以更好的支持 SEO，比如 [Guide](guide.md "The greatest guide in the world")。

  3. 扩展语法，包含强调内容，图片尺寸，html 和markdown 混用等。

  4. 直接显示被嵌入的文件内容。

  5. 搜索配置有一项叫 pathNamespaces: ['/en']，就是如果有多语言，当切换到 en 时，只在 en 目录搜索，不然会搜到中文里的内容。

  6. 用了 PWA 模式，导致本地预览无法自动刷新，清除浏览器数据才行，还是别开启了。

  7. 评论系统 Disqus 需要科学上网。waline 或 valine 用的 leancloud，国内要备案，国际版真正发评论时也得科学上网。Gitalk 要填一些 id/secret，且库必须公开，文件一看源代码全都显示出来。cusdis 如果自托管需要连接一个服务器上的数据库。算了。

  8. CDN 配的这个 <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script> 不能用，会引起搜索框出错，页面无法滑动。

  9. 代码高亮要支持一种语言就要加一句 script，比如要支持 java，就要添加 <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>，支持的语言种类在 Prism (prismjs.com)。

  10. formatUpdated: '{YY}-{MM}-{DD} {HH}:{mm}'，记录的是文章最后的修改时间，然后在文档里面插入{docsify-updated}，会解析成定义格式的日期时间。docsify-updated 插件自动在每个页面显示更新时间，代替 formatUpdated 配置。但是部署到 Vercel 后，两种方式都无法获取到时间。

  11. mermaid 组件的支持
    文档有两句被注释掉了，因为它的说明文档不需要引入，但实际上是需要的，css 放到 head 里，script 放到 body 里。然后文档上的

    var num = 0; 
mermaid.initialize({ startOnLoad: false });

    这两句也极其的莫名其妙，不知道放在哪里，后来用Docsify画图建模Mermaid插件支持写的方法可以正常显示，和官方的代码对比，发现官方的配置只要使用下面的就能正常显示：

    markdown: {
	renderer: {
		code: function(code, lang) {
			if (lang === "mermaid") {
				// 最大的问题就是原来 code 这里写的是 
				// mermaid.render('mermaid-svg-' + num++, code)
				// 但这句执行有问题，不懂
				return ('<div class="mermaid">' + code + "</div>");
			}
			return this.origin.code.apply(this, arguments);
		}
	}
}

  12. Footer 加点东西

    plugins: [
	function(hook) {
		var footer = [ // 就是字符串拼接出 html 语句
			'<hr/>',
			'<footer>',
			'<span>&copy;2023.</span>',
			'<span>Powered by ',
			'<a href="https://docsify.js.org/#/" target="_blank">docsify</a> v',
			window.Docsify.version, // 能获取到当前用的版本
			'</span>',
			'</footer>'
			].join('');
		hook.afterEach(function(html) {
			return html + footer;
		});
	}
]

  13. 更多的插件。太多属于年久失修状态，下面是一些能用的