Skip to main content

使用 Docsify 写笔记

· 4 min read

Docsify 是一个简单易用的文档框架

官方文档： https://docsify.js.org/

doscify 使用 markdown 写文章内容，但相对于其它静态博客生成器，docsify 是在运行时生成页面的，无需编译，直接部署 md 文件即可。

docsify 的缺点是对于 SEO 不够友好，不过还是会被搜索引擎收录。另外浏览器编译会消耗资源。

快速开始​

如果有 Node.js 环境，可以全局安装 docsify-cli 

npm i docsify-cli -g

然后在一个新建的目录中初始化

docsify init ./docs

会在路径下生成几个文件

index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

可以手动往 README.md 写一些内容

本地启动，默认访问地址 http://localhost:3000 

docsify serve docs

对于没有 Node.JS 环境，也可以使用手动初始化，新建一个 index.html 文件，填入如下内容

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

同样地，新建 README.md

可以使用 python3 启动一个简单的服务器，访问地址 http://localhost:8000 

python -m http.server

文档路径​

如果文档路径为

.
└── docs
    ├── README.md
    ├── about.md
    └── note
        ├── README.md
        ├── note1.md
        └── note2.md

则对应的访问路径是

docs/README.md        => http://domain.com/#/
docs/about.md         => http://domain.com/#/about
docs/note/README.md   => http://domain.com/#/note/
docs/note/note1.md    => http://domain.com/#/note/note1
docs/note/note2.md    => http://domain.com/#/note/note2

需要注意 url 末尾的斜杠

侧边栏​

打开侧边栏需要在 index.html 中将 loadSidebar 设为 true

<!-- index.html -->
<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>

在当前路径下新建 _sidebar.md 文件，并填入自定义侧边栏的内容

* [文章](posts/)
* [生活](life/2021)
* [笔记](note/)
* [关于](about/)

侧边栏会优先寻找当前路径下的 _sidebar.md 文件，如果没有，一层一层往上层路径寻找

侧边栏可以有多级的深度，设置方法

<script>
  window.$docsify = {
      subMaxLevel: 1
  }
</script>

导航栏​

导航栏位于顶部，开启导航栏需要设置 index.html 

<!-- index.html -->
<script>
  window.$docsify = {
    loadNavbar: true
  }
</script>

在当前路径下新建 _navbar.md 文件，按照如下格式设置导航栏

<!-- _navbar.md -->

* [文章](posts/)
* [生活](life/2021)
* [笔记](note/)
* [关于](about/)

代码高亮​

内置代码高亮是 Prism ，默认支持

Markup - markup, html, xml, svg, mathml, ssml, atom, rss
CSS - css
C-like - clike
JavaScript - javascript, js

需要额外的语法高亮支持需要添加 语法文件 ，例如

<script src="//cdn.jsdelivr.net/npm/[email protected]/components/prism-java.min.js"></script>

min 版本的是去掉一些空格回车的，体积小一点

配置​

由于浏览器缓存，一些新更新的内容可能因为缓存而看不到

设置不缓存（不确定有效）

<!--不缓存-->
<meta http-equiv="Expires" content="0">
<meta http-equiv="Pragma" content="no-cache">
<meta http-equiv="Cache-control" content="no-cache">
<meta http-equiv="Cache" content="no-cache">

统计流量​

通过设置 data-ga 来记录流量

<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" data-ga="UA-XXXXX-Y"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>

注意这里已经有了 docsify.min.js ，如果引用 2 次会导致问题，如无法下拉页面。