计算机基础 | 文档神器docsify安装及基本使用
为啥要用docsify？
神器Docsify让你的文档变得美观，配合typora，从此爱上看文档，各种优点：小巧、快速、美观、方便、快捷、上手快，可以浏览如下优秀案例
更多案例请看：Awesome Docsify
安装
1、首先安装npm：
sudo apt install npm
如果报错，则执行如下命令安装相关依赖
sudo apt-get install nodejs-dev node-gyp libssl1.0-dev
然后再执行安装命令：
sudo apt install npm
2、安装docsify-cli:
npm i docsify-cli -g
基本使用
1、初始化项目：
在项目的文档记录文件./docs目录里写文档，通过init初始化项目
docsify init ./docs
初始化成功后，在./docs目录会有如下几个文件
-
index.html，这是入口文件，不做解释 -
README.md，主页内容，不做解释 -
.nojekyll，这是用于阻止Github Pages忽略掉下划线开头的文件
2、本地预览网站
docsify serve docs
默认访问：http://localhost:3000/
如需修改端口号：
docsify serve docs --port=3001
进一步优化
如何添加侧边栏呢？
1、首先在index.html中将loadSidebar设置为true：
<!-- index.html -->
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
2、创建_sidebar.md
<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md)
注：如果要上传到Github Pages的话，需要在./docs中包含.nojekyll
文档结构大致如下：
└── docs/
├── _sidebar.md
├── .nojekyll
├── index.html
├── getting-started.md
└── running-services.md
设置目录展开级别，在index.html中设置subMaxLevel即可：
<!-- index.html -->
<script>
window.$docsify = {
loadSidebar: true,
subMaxLevel: 2
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
如何添加各种插件呢？
1、 添加全文搜索插件：
<script>
window.$docsify = {
search: 'auto', // default
search : [
'/', // => /README.md
'/guide', // => /guide.md
'/get-started', // => /get-started.md
'/zh-cn/', // => /zh-cn/README.md
],
// complete configuration parameters
search: {
maxAge: 86400000, // Expiration time, the default one day
paths: [], // or 'auto'
placeholder: 'Type to search',
// Localization
placeholder: {
'/zh-cn/': '搜索',
'/': 'Type to search'
},
noData: 'No Results!',
// Localization
noData: {
'/zh-cn/': '找不到结果',
'/': 'No Results'
},
// Headline depth, 1 - 6
depth: 2,
hideOtherSidebarContent: false, // whether or not to hide other sidebar content
// To avoid search index collision
// between multiple websites under the same domain
namespace: 'website-1',
// Use different indexes for path prefixes (namespaces).
// NOTE: Only works in 'auto' mode.
//
// When initialiazing an index, we look for the first path from the sidebar.
// If it matches the prefix from the list, we switch to the corresponding index.
pathNamespaces: ['/zh-cn', '/ru-ru', '/ru-ru/v1'],
// You can provide a regexp to match prefixes. In this case,
// the matching substring will be used to identify the index
pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/
}
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
2、添加代码复制插件：
<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>
3、添加latex公式插件:
<script src="//cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js"></script>
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/katex@latest/dist/katex.min.css"/>
更多插件可以参考：Awesome docsify plugins
