Docsify 全攻略

前言

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

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

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

源码:github.com/markz-demo/...

Demo:markz-demo.github.io/mark-docsif...

先看下效果:

比较

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

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

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

初始化

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

bash 复制代码
npm i docsify-cli -g
docsify init ./docs

然后按官方文档添加navbarsidebar,以及markdown文件,结构如下:

基本配置

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

javascript 复制代码
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主题:

html 复制代码
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">

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

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

plugins

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

javascript 复制代码
window.$docsify = {
  ...,
  search: {
    maxAge: 1,
    placeholder: {
      '/zh/': '搜索',
      '/': 'Type to search',
    },
    noData: {
      '/zh/': '找不到结果',
      '/': 'No Results',
    },
    depth: 6,
    hideOtherSidebarContent: true, // 建议设置true,搜索时搜索结果跟侧边栏混在一起了很不友好
    pathNamespaces: ['/zh', '/'], // 如果是多语言,建议设置此配置,搜索时就会只在当前语言下搜索
  },
html 复制代码
<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 )显示在右侧边栏,更符合当下流行的文档网站布局。支持滚动高亮,点击跳转等。

javascript 复制代码
window.$docsify = {
  ...,
  toc: {
    tocMaxLevel: 5,
    target: 'h2, h3, h4, h5, h6',
    ignoreHeaders: ['<!-- {docsify-ignore} -->', '<!-- {docsify-ignore-all} -->']
  },
html 复制代码
<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,可以通过覆盖样式临时解决:

css 复制代码
/* 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。

javascript 复制代码
window.$docsify = {
  ...,
  tabs: {
    persist: true,
    sync: true,
    theme: 'classic',
    tabComments: true,
    tabHeadings: true
  },
html 复制代码
<script src="//cdn.jsdelivr.net/npm/docsify-tabs@1.6.1/dist/docsify-tabs.min.js"></script>
markdown 复制代码
### Header 3

<!-- tabs:start -->

#### **English**

Hello!

#### **French**

Bonjour!

#### **Italian**

Ciao!

<!-- tabs:end -->

Markdown

代码高亮

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

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

html 复制代码
<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>

间距

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

css 复制代码
/* section */
.markdown-section pre {
  padding: 0;
}

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

效果:

深色主题

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

docsify-dark-switch

github.com/markz-demo/...

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

html 复制代码
<!-- 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,可以方便外部自行设置深色样式。

css 复制代码
/* theme color */
:root {
  /* 即themeColor值 */
  --theme-color: #42b983;
}

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

然后覆盖其它样式:

css 复制代码
/* 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把站点部署到本地,比如一个虚拟机:

bash 复制代码
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...

相关推荐
懒大王爱吃狼23 分钟前
Python教程:python枚举类定义和使用
开发语言·前端·javascript·python·python基础·python编程·python书籍
逐·風4 小时前
unity关于自定义渲染、内存管理、性能调优、复杂物理模拟、并行计算以及插件开发
前端·unity·c#
Devil枫5 小时前
Vue 3 单元测试与E2E测试
前端·vue.js·单元测试
尚梦5 小时前
uni-app 封装刘海状态栏(适用小程序, h5, 头条小程序)
前端·小程序·uni-app
GIS程序媛—椰子6 小时前
【Vue 全家桶】6、vue-router 路由(更新中)
前端·vue.js
前端青山6 小时前
Node.js-增强 API 安全性和性能优化
开发语言·前端·javascript·性能优化·前端框架·node.js
毕业设计制作和分享7 小时前
ssm《数据库系统原理》课程平台的设计与实现+vue
前端·数据库·vue.js·oracle·mybatis
清灵xmf9 小时前
在 Vue 中实现与优化轮询技术
前端·javascript·vue·轮询
大佩梨9 小时前
VUE+Vite之环境文件配置及使用环境变量
前端
GDAL9 小时前
npm入门教程1:npm简介
前端·npm·node.js