Loading... <div class="tip share">请注意，本文编写于 2013 天前，最后修改于 1971 天前，其中某些信息可能已经过时。</div> 当你有了一个全新的项目，但是有着大量的帮助文档和技术细节时，Github的wiki可能就不是那么好用了，而且很有可能我们需要一个单独的网站来展示项目和技术文档，庞大的技术文档库如何生成一个网站呢？ <!--more--> 面对这样的需求，很多的企业选择了自建wiki或者类似的系统，但是这样需要占用一部分服务器资源，而很多的开发者并没有精力去维护一个单独的文档网站。直到Docsify的出现。 Docsify的项目地址在[这里](https://docsify.js.org/#/)，这个项目的文档网站也是通过其本身生成的。 ## 本地环境&&初始化 Docksify提供了一个cli工具用于初始化项目&实时预览，这个cli是基于Nodejs的，也就是意味着先要在本地安装nodejs，这一部分非常简单，本篇文章重点放在Docsify的cli和基础的使用部分。 在安装完成Nodejs环境之后，只需要在命令行中 ```sh npm i docsify-cli g ``` 接下来切换到项目的根目录，如果是已有项目，并且需要在`./docs`中写文档，可以 ```sh docsify init ./docs ``` 如果只是单纯的文档项目，我们可以直接 ```sh docsify init . ``` 是不是很像`git init`？初始化完成之后我们可以在相应目录下看到下列文件 - `index.html` 记录自定义配置，同时也是入口文件 - `README.md` 主页面内容 - `.nojekyll` 阻止Github Pages忽略下划线开头的文件 ##编写&&实时预览 Docsify提供了一个LiveReload的server可以让我们实时看到更改的效果，降低了学习和调试的成本，默认的端口是3000，即[http://localhost:3000](http://localhost:3000) ```sh docsify serve docs ``` ### 扩展语法 我把这个部分放在前面，是因为这部分的扩展语法算是经常会使用的，而且handsome主题也在此基础上进行了一定的扩展。 ```md !> 一段重要的内容，可以和其他 **Markdown** 语法混用。 ```  ```md ?> _TODO_ 完善示例 ```  ### 自定义index.html ```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="//unpkg.com/docsify/themes/vue.css"> </head> <body> <div id="app">[加载提示语]</div> <script> window.$docsify = { [配置项] } </script> <script src="//unpkg.com/docsify/lib/docsify.min.js"></script> </body> </html> ``` 配置项的种类算是非常丰富的，你可以简单地通过一些配置项的变更，实现高度的自定义 - `repo` 可以在右上角渲染Github Corner挂件 - `maxLevel` 配置最大支持渲染的标题层级，默认为6 - `loadNavbar` 加载自定义导航栏配置 - `loadSidebar` 加载自定义侧边栏配置 - `auto2top` 切换页面后跳转到顶部 - `coverpage` 启用封面页 还有很多，可以参考官方文档 ### 侧边栏与导航栏 #### 侧边栏 开启了`loadSidebar`我们就可以使用`_sidebar.md`配置侧边栏，这里是一个简单的例子 ```md - **快速开始** - [快速开始](快速开始.md) - **进阶用法** - [进阶用法](进阶用法.md) - [小技巧](小技巧.md) ``` 还可以设置`subMaxLevel`开始目录功能，对于文档中的某些标题，我们可以选择忽略 ```md # Getting Started ## Header {docsify-ignore} 该标题不会出现在侧边栏的目录中。 ``` 或者直接忽略所有标题 ```md # Getting Started {docsify-ignore-all} ## Header 该标题不会出现在侧边栏的目录中。 ``` 在使用时， {docsify-ignore} 和 {docsify-ignore-all} 都不会在页面上呈现。 #### 导航栏 你可以直接在`index.html`中定义导航栏，不过我更推荐在`_navbar.md`中定义，这样修改起来更加直观。 这里有一个简单的例子 ```md * [En](/) * [中文](/zh-cn/) ``` 如果写成了嵌套列表，docsify会帮你渲染成下拉列表 ### 封面 开启`coverpage`选项后，docsify会从`_coverpage.md`中读取配置 ```md  # 炮兵小队 > 可能是最理想的校园网工具 * 全面支持下一代网际协议 * 高效代码 轻量工具 * 钻石品质线路 [访问网站](https://issacc.bid ':target=_blank') [开始使用](快速开始) ``` 默认的背景是随机生成的渐变色，自定义背景图或背景色可以 ```md   ``` ### 更换主题 Docsify现有三套主题可选，只需要在`index.html`中替换相应的css文件 ```html <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css"> <link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css"> <link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css"> <link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css"> <link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css"> ``` ### 插件 docsify的插件不算非常丰富，但是可以满足中小型项目的文档需求，你可以在[这里](https://docsify.js.org/#/zh-cn/plugins)找到Docsify的插件和配置方法，比较常用的有全文搜索和图片缩放。配置插件大多都比较简单，只需在`index.html`中引入一些js ## 部署 Docisfy支持部署到你的VPS，Github Pages，Gitlab Pages等服务。这里我们简单的介绍Github Pages是如何部署的，VPS的部署非常简单，只需要你的Nginx指向你的文档根目录即可 Github上新建repo或将文档放在已有repo下的docs目录下，在设置页面开启Github Pages并选择合适的位置，即可发布文档，如果你需要自定义域名，只需在文档根目录放置记录自定义域名的CNAME文件。 我的加速服务的技术文档就是由Docisfy生成的，有兴趣的可以来[看看成品](https://top.issacc.top) 最后修改：2019 年 04 月 19 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏
2 条评论
$ docsify init ./docs
-bash: docsify: command not found
第二步就显示无此命令
抱歉这么晚才回复，我认为是你的npm没有写入bash的环境里，这一步在Windows上确实需要配置环境变量才能正常使用。