Intro

如果要给项目写文档，还能自带部署为前端，如果可以导出pdf、html啥的就更好了，当然能导出epub等电子书格式就更好了

本文内容经i有限，zhi描述了gitbook、docsify、docusaurus，主要是放在了docsify上

下期可能的对象：sphinx

gitbook

:20210305 23.4k Star ,3.5k Fork

已经在2018年被抛弃！ 抛弃！ **抛弃！**原班人马去创业赚钱ing,这里只是做个古董开箱。。

install

sudo npm install gitbook-cli -g

demo

$ gitbook init ./book
Installing GitBook 3.2.3
/usr/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
      if (cb) cb.apply(this, arguments)
                 ^

TypeError: cb.apply is not a function
    at /usr/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
    at FSReqCallback.oncomplete (node:fs:201:5)

emmm整了老半天最后不整了。。。此外新的gitbook需要科学上网。。

docsify

:20210305 16.9k Star ,4.1k Fork

使用感受：优点是很简单，写md就行了，也不需要配置啥主题啥域名（hugo、hexo需要）。

可以看到比较简洁，只有左侧有全局侧边栏（可自动识别文章内部标题），还可以配置各种插件，顶部配置的语言切换导航栏，说实话，棒！！

在其中，其推荐将文档放置在项目的docs目录下，直接使用page服务将/docs部署，NB这样都不用hugo转成静态这一步骤了。

install

node + npm

$ sudo pacman -S nodejs  npm

$ node -v
v15.11.0

$ npm -v
7.6.1

docsify

sudo npm i docsify-cli -g

added 220 packages, and audited 221 packages in 5m
13 packages are looking for funding
  run `npm fund` for details
3 moderate severity vulnerabilities
To address all issues, run:
  npm audit fix

Run `npm audit` for details.

init

$ docsify init  /home/kearney/Documents/code/docsify
/home/kearney/Documents/code/docsify already exists.
✔ Are you sure you want to rewrite it? (y/N) true

Initialization succeeded! Please run docsify serve /home/kearney/Documents/code/docsify

[kearney@arch docsify]$ docsify serve

Serving /home/kearney/Documents/code/docsify now.
Listening at http://localhost:3000

自己尝试写了下，太舒服了

pdf plugin

导出pdf的功能在插件列表里面看到一个支持的插件

npm install --save-dev docsify-pdf-converter

这个安装着实让人蒙蔽，全安到我主目录下了。。。

按照仓库里的readme进行操作，在docs里新建.docsifytopdfrc.js和package.json，然后修改对应的信息之后 npm run convert。

emm，着实吓到我了，首先右上角每一页都有绿标github.。。。。。不过这个可以在文档首页设置取消，可以明显看出是按照sidebar去做快照的。还有个问题就是没有书签目录。。

docusaurus

：20210305 22.1k Star ,2.7k Fork 顶部的导航栏有较多选择项。主体部分除了左侧的全局导航栏之外，右侧还有局部导航栏。 翻译一下其README的重要信息 - Docusaurus 是一个轻松构建，部署和维护网站的开源项目。 写博客的话分类和标签功能不如hugo.。主要用来写产品网站。。。

Refer

Deprecation warning(弃用警告) As the efforts of the GitBook team are focused on the GitBook.com platform, the CLI is no longer under active development. All content supported by the CLI are mostly supported by our GitBook.com / GitHub integration. Content hosted on the legacy.gitbook.com will continue working until further notice. For differences with the new vesion, check out our documentation.

：20210305 22.1k Star ,2.7k Fork

：20210305 42.3k Star ,9.2k Fork

:为python而生。。文档也是用它

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, written by Georg Brandl and licensed under the BSD license. It was originally created for the

老玩家了

End