最简单的Markdown文档生成工具 book-cli

目前的文档编写工具，我想大概推荐：

• gitbook
• vuepress
• ydoc

其他的我都不太清楚了，还有一些国内文档编写的网站，各种选择。

是的，造轮子的人又来了。

当下的问题：

gitbook

我就不说了，代码老旧，控件库质量层次不齐，我改了一天，勉强能看，再弄弄，居然有bug，果断放弃。

还有上传同步那一套，搞得我摸不清头脑....

vuepress

尤大的团队，还是很值得信任的，功能我看了，是梦想中的功能。

当时写一半的时候看到vuepress，当时有考虑过直接用vuepress。

只是吧，文档居然能有那么长，然后又是安装，又是部署，想想应该没有多少人访问的网站，我还是自己写个吧。

ydoc

我觉得ydoc还是很不错的，就是我在一开始写文档的时候，一直想不起名字，导致，我一直没有找到它。

但是，我刚刚试用了一下，还是很多细节有欠缺，感觉自己改起来应该比较麻烦。

比如说，返回顶部，或者段落标题hash，和vuepress相比的话，缺乏很多细节。

不多说了，总之，自己写的用起来比较爽，好改。

Book-Cli

book-cli 是一个简单的静态页面，用于快速生成说明文档网站。

简单来说，book-cli 不需要编译，你可以通过直接编写

Markdown

文件，达到文档网站的构建。

它是如何工作的？

其实，book-cli 是通过

marked

,

prism

等控件，直接使用

javascript

读取

Markdown

文件，解析文件，再渲染页面。

所以，不需要编译，自动化部署简单（提交代码即可），入门难度极低。

初始化项目

我们提供以下三种方案初始化项目：

下载代码

建议从 book-cli 的 github 中下载代码至本地。

Fork

在github中直接fork项目。

项目拷贝

使用git拷贝项目，以下为示例代码：

git clone https://github.com/vvpvvp/book-cli.git my-project
  git remote set-url origin my-project-github-address
  git push
复制代码
           

当然，你也可以通过其他方式初始化项目，简单的来说，就是代码拷贝。

配置

根目录下

config.js

文件

var CONFIG = {
  // 网页 title
  title: 'Book-Cli',
  // 网页 keywords
  keywords: 'book, book-cli, doc, example',
  // 网页 description
  description: 'Init html book with markdown files.',
  // 页面右上角的 github 链接
  github: 'https://github.com/vvpvvp/book-cli',
  // 左侧目录的md文件
  summaryMd: 'SUMMARY.md',
  // 网页默认访问的md文件
  index: 'README.md'
}
复制代码
           

部署

编写完文档后，将整个目录上传至服务上，设置访问即可。

Github 部署

Github提供了免费的静态页面部署服务，所以，你可以免费的发布自己的文档项目。

项目 -> Setting -> GitHub Pages -> 选择master分支 -> 点击Save

之后，你就可以访问文档网站了。

维护

项目维护极其简单，直接维护md文档就可以了。

优缺点

优点

• 快速入门
• 无需编译
• 快速部署（静态系统，随意扔在服务器上即可）
• 自定义极强（纯静态系统，可以随意修改）
• 适配PC端与移动端
• 界面好看（脸皮较厚）

缺点

• 未编译成html，对于搜索引擎不友好（其实现在搜索引擎只需要收录下首页）
• 功能没有那么强大
• 没有全网搜索

最后

说了那么多，期待大家的尝试-->期待star ✨✨

github.com/vvpvvp/book…

在线文档：

vvpvvp.coding.me/book-cli/#R…

示例文档（我自己整理的ECMAScript 6文档）:

es6.ch-un.com/

最后的最后

希望大家关注我的Vue开源库 HeyUI