Docsify 全攻略

前言

最近项目有个需求是想做个内部文档网站，用于介绍项目及内部培训，当前比较流行的方案是直接用Markdown编写文档内容，然后通过js读取Markdown内容，然后转换成html，最后展示在页面上。

研究了下市面上比较流行的静态站点生成器（SSG），最后选用 Docsify 来做文档网站。其中看好的优点是：

1. 不需要安装任何依赖，不需要编译，完全运行时驱动。静态文件里只需要放入一个html文件，然后再放入Markdown文件就可以了。
2. 不需要SEO，纯展示Markdown内容，不需要高级或复杂的功能。

源码：github.com/markz-demo/…

Demo：markz-demo.github.io/mark-docsif…

先看下效果：

比较

当下比较流行的静态站点生成器还有 VitePress 和 VuePress，都是Vue团队的产品，相比 docsify，它们功能更强大，许多功能开箱即用，而且也有很多扩展，最重要的是SEO支持很友好。

但是 docsify 的优点是：不需要安装任何依赖，不需要编译，完全运行时驱动，功能虽然少，但是对于一个简单的文档网站足够用了，需要的特殊功能也可以通过自定义插件实现，然后是项目内部使用的站点，不需要SEO。

更多区别参考 为什么不是...?

初始化

可以使用 docsify-cli来快速初始化，也可以自己手动创建html，很简单。

npm i docsify-cli -g
docsify init ./docs

然后按官方文档添加navbar和sidebar，以及markdown文件，结构如下：

基本配置

先列下 docsify 的基本配置。更多配置参考：docsify

window.$docsify = {
  name: 'mark-docsify',
  nameLink: { // 多语言下,点击name跳转链接
    '/zh/': '#/zh/',
    '/': '#/',
  },
  repo: 'https://github.com/markz-demo/mark-docsify',

  auto2top: true, // 每次切换页面后自动跳转到页面顶部
  loadNavbar: true,
  loadSidebar: true,
  // subMaxLevel: 2, // 是否把文档里的目录显示在侧边栏里，这里设置不显示，下面有介绍更好用的toc插件实现
  alias: {
    '/.*/_navbar.md': '/_navbar.md', // 配置 alias 避免不必要的回退过程
    '/.*/_sidebar.md': '/_sidebar.md',
  },
}

然后执行下docsify serve docs，就能看到效果：

主题色

样式主题引用的是docsify官方默认light主题：

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">

然后，需要通过 themeColor 属性设置主题色，虽然有默认主题色，但是，设置后会在root上自动添加--theme-colorcss变量，然后很多plugins里都会基于这个主题色css变量，所以建议最好设置上。

window.$docsify = {
  ...,
  themeColor: '#42b983', // 设置主题色，即官方vue.css中对应的主题色

plugins

search

参考：docsify.js.org/#/zh-cn/plu…

window.$docsify = {
  ...,
  search: {
    maxAge: 1,
    placeholder: {
      '/zh/': '搜索',
      '/': 'Type to search',
    },
    noData: {
      '/zh/': '找不到结果',
      '/': 'No Results',
    },
    depth: 6,
    hideOtherSidebarContent: true, // 建议设置true，搜索时搜索结果跟侧边栏混在一起了很不友好
    pathNamespaces: ['/zh', '/'], // 如果是多语言，建议设置此配置，搜索时就会只在当前语言下搜索
  },

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

吐槽下，这个侧边栏上面的search框很丑，而且也不支持搜索结果弹框显示，希望能做成跟 VitePress 那样顶部导航中间显示搜索框的，然后结果可以popup显示，找了一圈没找到。

另外推荐一款支持 algolia 的 search plugin： docsify-algolia-search-plugin

docsify-plugin-toc

github.com/justintien/… 这个插件可以把文档里的header（也就是目录，Table of Content ）显示在右侧边栏，更符合当下流行的文档网站布局。支持滚动高亮，点击跳转等。

window.$docsify = {
  ...,
  toc: {
    tocMaxLevel: 5,
    target: 'h2, h3, h4, h5, h6',
    ignoreHeaders: ['<!-- {docsify-ignore} -->', '<!-- {docsify-ignore-all} -->']
  },

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-plugin-toc@1.3.1/dist/light.css">
...
<script src="//cdn.jsdelivr.net/npm/docsify-plugin-toc@1.3.1/dist/docsify-plugin-toc.min.js"></script>

效果：

bug

有一个bug，如果切换了右侧Toc，url会自动加上id参数，会导致左侧导航不高亮，感觉是docsify的bug，可以通过覆盖样式临时解决：

/* sidebar active bug */
.sidebar ul li[class=""]>a {
  border-right: 2px solid;
  color: var(--theme-color);
  font-weight: 600
}

docsify-tabs

github.com/jhildenbidd… 可以在markdown里回显tabs。

window.$docsify = {
  ...,
  tabs: {
    persist: true,
    sync: true,
    theme: 'classic',
    tabComments: true,
    tabHeadings: true
  },

<script src="//cdn.jsdelivr.net/npm/docsify-tabs@1.6.1/dist/docsify-tabs.min.js"></script>

### Header 3

<!-- tabs:start -->

#### **English**

Hello!

#### **French**

Bonjour!

#### **Italian**

Ciao!

<!-- tabs:end -->

Markdown

代码高亮

docsify内置的代码高亮工具是 Prism，默认支持的语言不多，所以如果Markdown里有不支持的语言，需要自己额外语法文件。

参考：docsify.js.org/#/zh-cn/lan…

<script src="//cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1.29.0/components/prism-jsx.min.js"></script>

间距

个人感觉默认的内嵌代码间距太大了，不好看，可以覆盖样式调整合适的间距。

/* section */
.markdown-section pre {
  padding: 0;
}

.markdown-section pre>code {
  padding: 1rem;
}

效果：

深色主题

就是可以切换浅色和深色主题，类似VitePress 自带的效果：

docsify-dark-switch

github.com/markz-demo/…

首先，推荐下我写的主题切换插件，用法很简单，只需以下引用：

<!-- head -->
<!-- set theme stylesheet the corresponding title, you can set multiple  -->
<link rel="stylesheet" title="light" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<link rel="stylesheet" title="dark" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">

<!-- link docsify-dark-switch.css  -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-dark-switch/dist/docsify-dark-switch.css">

<style type="text/css">
    /* navs fixed 顶部导航fixed固定*/
    .app-nav {
      position: fixed; 
    }
</style>

<!-- body -->
<script>
window.$docsify = {
    // ...
    darkSwitch: {
        fixed: true, // switch按钮fixed固定
    },
    // ...
}
</script>

<!-- script docsify-dark-switch.js or docsify-dark-switch.min.js  -->
<script src="//cdn.jsdelivr.net/npm/docsify-dark-switch/dist/docsify-dark-switch.min.js"></script>

个人比较喜欢让顶部导航固定，即不随滚动条滚动，可以通过覆盖样式实现，效果：

可以看到，有些地方在深色模式下样式支持的不好，特别是有些plugin，所以还得优化下。

优化

首先得定义一个深色模式下的主题色，docsify-dark-switch plugin在切换深色时，会默认给html添加一个dark class，可以方便外部自行设置深色样式。

/* theme color */
:root {
  /* 即themeColor值 */
  --theme-color: #42b983;
}

html.dark {
  /* 深色主题色 */
  --theme-color: #ea6f5a;
}

然后覆盖其它样式：

/* toc */
.page_toc div[class^="lv"] a {
  font-weight: 400;
}

:root {
  --sidebar-nav-link-color--active: var(--theme-color);
}

html.dark {
  --sidebar-nav-link-color: #c8c8c8;
}

/* table dark */
html.dark .markdown-section tr:nth-child(2n) {
  background-color: #4f4f4f;
}

/* tabs */
html.dark {
  --docsifytabs-tab-background: #4f4f4f;
}

html.dark .docsify-tabs--classic>.docsify-tabs__tab--active {
  border-top: none;
}

优化完的效果：

其它

其它还有很多很实用的插件，具体可以参考官方文档：插件列表 | Awesome Docsify

部署

部署到服务器方式很多，可以参考官方文档：部署。这里主要介绍最简单的部署方式，通过PM2把站点部署到本地，比如一个虚拟机：

npm install pm2@latest -g // 全局安装npm2
pm2 serve . 3000 --spa --name docs // 启动服务

npm install pm2-windows-startup -g // 如果是windows系统，需要先装下这个
pm2 save // 保存进程
pm2 startup // 开启自动启动

• 如服务意外挂了会自动重启。
• 每次开机自动启动。
• 替换docs下静态文件后，自动重新部署。

更多PM2命令参考：文档 | 中文

总结

本文主要介绍了一款比较流行的 静态站点生成器（SSG）Docsify 全攻略用法，包括基本配置及一些插件，个人感觉，如果只是想做一个简单的文档网站，不需要做的太好看或者很多功能，用 Docsify 以及少了插件就足够满足需求了。

如果你也有此类需求，Docsify 是一个比较好的选择。

源码：github.com/markz-demo/…

Demo：markz-demo.github.io/mark-docsif…