最简单的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