docsify

约 700 字大约 2 分钟...

docsifyopen in new window 是一个神奇的文档网站生成器,可以快速帮你将 md 文档生成为网站。docsify 入门简单且无需服务器,非常适合个人笔记的简单整理分享。

本页集中了我使用 docsify 中遇到的问题,新手先看 docsify 入门文档open in new window

插件

docsify 插件列表open in new window

配置

emojiopen in new window

emoji 插件在标题中使用容易出错,建议使用 :。例如,原本是 :100:,替换为 :100:

实际使用中,我直接复制 emoji,都能正常显示。

本地命令open in new window

<path> 默认为当前路径,可使用子文件夹指定路径,如 ./docsdocs

[] 为可省略命令区,无实际作用,输出时需要去除。

Serve 启动

如果你想在电脑上查看 docsify 页面,可执行 serve 架构命令,在本地主机上运行服务。默认本地端口为 3000,可以指定端口。

docsify serve <path> [--open false] [--port 3000]

使用时不要关闭命令终端,否则 serve 也会停止。

生成侧边栏

docsify generate <path> [--sidebar _sidebar.md]

generate 命令会遍历指定目录及其子目录的所有 markdown 文件,并生成全路径的 _sidebar.md。<path> 不能省略,需指定子文件夹路径。

如果路径中存在 _sidebar.md,则会报错。

常见问题

引用路径

docsify 引用内部文件时,路径会自带添加域名。

例如:指向子文档时,链接是 子文件夹/文档名.md;指向子文档的小标题时,链接是 子文件夹/文档名?id=小标题

页面未同步更新

CDN 默认是有缓存的,如果文件更新,访问的可能不是最新的文件。

我设置了 routerMode 为 history,使用 CDN 访问非首页,再次刷新会找不到文件。

如果开启了 relativePath: true,文件可以找到,但是侧栏上边的标题点击又有点问题。

GitHub Pages 报错

如果 SSL 链接 404 报错,显示「There isn't a GitHub Pages site here」,则目录中加入 CNAME 文件。

评论
Powered by Waline v2.6.3