2022-09-25 docsify 站点发布

docsify 终于算是弄完了，简单记录下。然后发现一个问题，相比 Hexo，Hugo 这些页面加载很慢，鱼与熊掌不可兼得，运行时生成只能这样了。

还有 navbar 的设置有时在封面无法显示。

主要参考官方文档，一次配置完的，一看就懂的就不需要记录了，记下可能后续需要改动的，花了一点时间才搞明白的。

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

    ![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%')
    

21. Footer 加点东西

    plugins: [
        function(hook) {
            var footer = [ // 就是字符串拼接出 html 语句
                '<hr/>',
                '<footer>',
                '<span>&copy;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;
            });
        }
    ]
    

22. 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);
            }
        }
    }