用 gitbook 为项目写本书吧

[imsobear]

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

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

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

1. 安装

cnpm 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 就可以很简单的完成部署了。

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

---

参考文章：

• gitbook on github

[WisestCoder]

为什么只要我更改了文件，就会报错啊？

楼主帮忙看看吧~

[imsobear]

@dushao103500 去谷歌搜索看看，或者去 gitbook 的 issue 里找下，我自己没有在 windows 下用过。