docsify
docsify 是一个神奇的文档网站生成器,可以快速帮你将 .md 文档生成为网站。docsify 入门简单且无需服务器,非常适合个人笔记的简单整理分享。
本页集中了我使用 docsify 中遇到的问题,新手先看 docsify 入门文档。
插件
illegal operation on a directory
报错:sidebar 中不要使用简写地址,将main/
改为main/README.md
,否则将读取到目录而报错。'node_modules' 不是内部或外部命令
报错:将 package.json 的设置修改为"convert": "node_modules\\.bin\\docsify-pdf-converter"
。这问题多发生在 Windows,是由 Windows 与 Linux 路径规则不同而引起的。
配置
docsify emoji
emoji 插件 在标题中使用容易出错,建议使用 :
。例如,原本是 :100:
,替换为 :100:
。
实际使用中,我直接复制 emoji,都能正常显示。
本地命令
<path>
默认为当前路径,可使用子文件夹指定路径,如 ./docs
或 docs
。
[]
为可省略命令区,无实际作用,输出时需要去除。
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
文件。