docsify 终于算是弄完了,简单记录下。然后发现一个问题,相比 Hexo,Hugo 这些页面加载很慢,鱼与熊掌不可兼得,运行时生成只能这样了。
还有 navbar 的设置有时在封面无法显示。
主要参考官方文档,一次配置完的,一看就懂的就不需要记录了,记下可能后续需要改动的,花了一点时间才搞明白的。
手动初始化不太懂,想着手写 html 拿它那些命令运行不需要环境之类的吗,被之前的 Hexo,Hugo 误导,还真不要,就一个 html 文件,里面引用的 js,就可以执行了。
文件名后加内容以更好的支持 SEO,比如 [Guide](guide.md "The greatest guide in the world")
。
需要 <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
配置的不能用,会引起搜索框出错,页面无法滑动。比如文档上的 CDN 插件就是这问题。
subMaxLevel 是文档内部的标题也显示到左侧导航目录上,并控制显示几级。第一个一级标题 #
显示不出来,之前 Hugo 也是,大概是默认将 #
当做文档的标题,也许这是一个约定的标准。
若小标题不需要加到目录(比如 README),在第一个标题后添加 `` 可以忽略文档所有标题,也可以添加标签去忽略指定标题。
index.html 中的 repo 是配置 Github 地址,会在网页右上角显示 Github 图标折角。
首页自定义显示卡片索引链接到具体文集,幸好之前学过前端,虽然不记得,笔记还在,不会用太复杂的,简单的还能写。
封面配置里不要用标题标签,不然点击会自动跳转,直接用 html 的 font 去设置。
封面的按钮,必须放在最下面,如果下面还继续写其它的,按钮默认样式会消失。除非自己用 html 代码写按钮,不然要保持它在最下面。
onlyCover: true
则不能在封面通过上下滑动到文档内容。
logo: '/_media/icon.svg'
侧边栏上面显示 logo,不设置 name 属性显示不出来,另外文档说用 CSS 控制大小,不会,最后只能压缩图片本身尺寸。
formatUpdated: '{YY}-{MM}-{DD} {HH}:{mm}'
,记录的是文章最后的修改时间,然后在文档里面插入{ docsify-updated }
(需要把大括号左右两边空格去掉,这里为了显示加上,因为一去掉就解析成时间值了),会解析成定义格式的日期时间。
搜索配置有一项叫 pathNamespaces: ['/en']
,就是如果有多语言,当切换到 en 时,只在 en 目录搜索,不然会搜到中文里的内容。
在做导航栏时,路径必须时当前根目录下的绝对路径才有效,文档内部链接,当前路径的相对路径和根目录下的绝对路径都有效,但图片,用绝对路径就加载不出来,必须用相对路径,真是奇怪极了。
代码高亮要支持一种语言就要加一句 script,比如要支持 java,就要添加 <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
,支持的语言种类在 Prism (prismjs.com)。
用了 PWA 模式,导致本地预览无法自动刷新,即便代码恢复也不行,因为被浏览器缓存了,清除浏览器数据才行。
代码传到 Github 的 private 库,然后 vercel 导入,官方没有 docsify 模版,就用 other 可以,第一次打开很慢还以为失败了呢。vercel 就用 github 登录,用邮箱每次都发邮件验证,超级麻烦。
评论系统 Gitalk,需要 Github,好像还必须填写 Github Pages 的仓库 url,但我是私有的库,没开 Pages 服务,只能放弃。后来用了docsify-waline: A simple comment plugin for docsify。虽然也不会有人评论,但有它功能完整些。结果不挂代理评论不了,所以还是隐藏了。
Awesome docsify列出的插件多属于年久失修系列,很多都不能用,不看也罢。
图片缩放的定制语法
![logo](https://docsify.js.org/_media/icon.svg ':size=WIDTHxHEIGHT')
![logo](https://docsify.js.org/_media/icon.svg ':size=50x100')
![logo](https://docsify.js.org/_media/icon.svg ':size=100')
<!-- 支持按百分比缩放 -->
![logo](https://docsify.js.org/_media/icon.svg ':size=10%')
Footer 加点东西
plugins: [
function(hook) {
var footer = [ // 就是字符串拼接出 html 语句
'<hr/>',
'<footer>',
'<span>©2022.</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;
});
}
]
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);
}
}
}