达尔文曾经说过：「任何一个项目都应该有一个 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/
作者：大果
