用 gitbook 为项目写本书吧

达尔文曾经说过：「任何一个项目都应该有一个 README」。

恩，README.md 对于任何一个项目来说都是不可或缺的一部分，无论是对于使用者还是后续维护者都是灰常重要哒:p

对于小型项目，一个 README.md 足以，但是如果是一个大项目的话（如 midway），那就不是一个 README.md 可以搞定的啦。本文就来扯一下使用 gitbook 为你的项目写一本**书**。

1. 安装

tnpm i -g gitbook

2. 初始化：

在你的文档目录下新建文件 SUMMARY.md，这个文件就是这本书的目录啦：

cd docs
touch SUMMARY.md

SUMMARY.md 的格式规范如下：

# uitest 文档

- [uitest 是什么](users/index.md)
    - [如何使用 uitest](users/use.md)
    - [如何编写自定义的测试用例](users/case.md)
    - [browserjs API 文档](users/api.md)
- [uitest 开发者文档](devs/index.md)
    - [browserjs 开发者文档](devs/browserjs.md)
    - [utci 文档](devs/utci.md)
    - [utserver & utclient 文档](devs/utserver.md)
- [相关文章沉淀](artical.md)
- [关于 gitbook](gitbook.md)

然后执行 gitbook init 初始化，gitbook 会根据 SUMMARY 的结构生成对应的目录文件：

├── README.md           // 首页
├── SUMMARY.md          // 目录
└── users               // 用户文档
    └── index.md        // 是什么
    ├── use.md          // 如何使用
    ├── api.md          // browserjs API
    ├── case.md         // 如何写测试用例
├── devs                // 开发者文档目录
│   ├── index.md        // 开发者文文档首页
│   ├── browserjs.md    // browserjs 开发文档
│   ├── utci.md         // utci 开发文档
│   └── utserver.md     // utserver 和 utclien 开发文档
├── artical.md          // 文章沉淀
├── gitbook.md          // gitbook 相关

3. 本地调试：

在对应的文档目录下运行 gitbook serve 会启动一个本地的静态服务器：

访问 http://localhost:4000/ 就可以实时的预览啦，并且支持 livereload, 灰常赞~接下来结合预览的功能编辑对应的文档，完成之后就可以发布啦。

4. 发布：

在文档目录下执行 gitbook build 会生成一个 _book 的目录，这个目录就是我们的静态网站啦，然后通过 demo 平台或者 github pages 就可以很简单的完成部署了。

因为 uitest 的 docs 本身就是在 Express 应用中的，因此我只需要在 express 中增加一个静态服务器即可：

app.use('/docs', express.static('docs/_book'));

然后访问 http://uitest.taobao.net/docs/index.html 即可。

上面说的都是做项目文档，但是如果你想写本书，那么 gitbook 提供了更为方便的服务，请移步 gitbook 官方网站

正文完。

文章转载自：http://sobear.me/

作者：大果