Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

用 gitbook 为项目写本书吧 #57

Closed
imsobear opened this issue Mar 17, 2015 · 2 comments
Closed

用 gitbook 为项目写本书吧 #57

imsobear opened this issue Mar 17, 2015 · 2 comments
Labels

Comments

@imsobear
Copy link
Owner

达尔文曾经说过:「任何一个项目都应该有一个 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 官方网站


参考文章:

@WisestCoder
Copy link

为什么只要我更改了文件,就会报错啊?
image
楼主帮忙看看吧~

@imsobear
Copy link
Owner Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

No branches or pull requests

2 participants