前言
最近项目有个需求是想做个内部文档网站,用于介绍项目及内部培训,当前比较流行的方案是直接用Markdown
编写文档内容,然后通过js
读取Markdown
内容,然后转换成html
,最后展示在页面上。
研究了下市面上比较流行的静态站点生成器(SSG) ,最后选用 Docsify 来做文档网站。其中看好的优点是:
- 不需要安装任何依赖,不需要编译,完全运行时驱动。静态文件里只需要放入一个html文件,然后再放入Markdown文件就可以了。
- 不需要SEO,纯展示Markdown内容,不需要高级或复杂的功能。
Demo:markz-demo.github.io/mark-docsif...
先看下效果:
比较
当下比较流行的静态站点生成器还有 VitePress 和 VuePress,都是Vue团队的产品,相比 docsify,它们功能更强大,许多功能开箱即用,而且也有很多扩展,最重要的是SEO支持很友好。
但是 docsify 的优点是:不需要安装任何依赖,不需要编译,完全运行时驱动,功能虽然少,但是对于一个简单的文档网站足够用了,需要的特殊功能也可以通过自定义插件实现,然后是项目内部使用的站点,不需要SEO。
更多区别参考 为什么不是...?
初始化
可以使用 docsify-cli
来快速初始化,也可以自己手动创建html
,很简单。
bash
npm i docsify-cli -g
docsify init ./docs
然后按官方文档添加navbar
和sidebar
,以及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-color
css变量,然后很多plugins里都会基于这个主题色css变量,所以建议最好设置上。
javascript
window.$docsify = {
...,
themeColor: '#42b983', // 设置主题色,即官方vue.css中对应的主题色
plugins
search
参考: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
首先,推荐下我写的主题切换插件,用法很简单,只需以下引用:
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下静态文件后,自动重新部署。
总结
本文主要介绍了一款比较流行的 静态站点生成器(SSG)Docsify 全攻略用法,包括基本配置及一些插件,个人感觉,如果只是想做一个简单的文档网站,不需要做的太好看或者很多功能,用 Docsify 以及少了插件就足够满足需求了。
如果你也有此类需求,Docsify 是一个比较好的选择。