# GitBook `GitBook`在线挂载时，需要注意：章节内容第一行请勿使用标题格式，否者会造成无法显示文章内容 ## 关于`GitBook`本地使用 更多教程看查看[其它博主的分享](https://www.chengweiyang.cn/gitbook/gitbook.com/edit.html) 有关更多`gitbook`命令可使用`gitbook help`获取 ### 下载GitBook并安装 需要使用`node`工具，没有`node`的需要先安装`node` > `GitBook`已停止维护，需要使用旧版本的`node`，附V10下载[链接](https://nodejs.org/download/release/v10.24.1/node-v10.24.1-x64.msi) * 安装`gitbook-cli`，如遇到权限问题，使用管理员权限运行CMD，后再执行 ```shell npm install -g gitbook-cli ``` > 此时`GitBook`并未执行安装，在首次执行`gitbook init`后，将执行安装 ### 书本初始化 在文件夹内下，打开`cmd`窗口，进行初始化 ```bash gitbook init ``` 初始化后，目录下会出现`README.md、SUMMARY.md`两个文件 * `README.md`表示对书本的介绍 * `SUMMARY.md`用于控制书本的结构 ### 书本构建 * 自动生成文件 在`SUMMARY.md`中写入目录后再次初始化，会自动创建文件目录及文件，例如： ```markdown # SUMMARY * [Chapter1](chapter1/README.md) * [Section1.1](chapter1/section1.1.md) * [Section1.2](chapter1/section1.2.md) * [Chapter2](chapter2/README.md) ``` * 构建书本 ```bash gitbook build ``` 会生成一个`_book`目录，储存`html`格式的书本内容 ### 书本查看 * 启动`serve`，会返回一个本地端口，即可在浏览器中查看书本 ```bash gitbook serve ``` * 发布书本为指定格式 ```bash gitbook pdf ``` ## `GitHub Pages`关联`GitBook` 为GitHub仓库设置说明文档，使用此方式非常合适且便捷 ### 书本初始化 同样需要在项目路径启动`CMD`，运行`gitbook init`进行初始化，会自动创建`README.md`和`SUMMARY.md` > 如果项目已有`README.md`，则只会新建`SUMMARY.md`，已有的`READEME.md`不会丢失 > > 如果书籍的内容在项目路径下的一个文件夹内，本例中为Wiki，则直接在Wiki下进行init即可 ### 书本构建 `SUMMARY.md`文件控制了整书本的结构，一般来说最多构建至二级目录 编辑完成`SUMMARY.md`，使用`build`命令构建 ```shell gitbook build Wiki docs ``` > 代码示例为：`Book` 相关内容全部放在Wiki目录下， 新生成的`html`文件将储存至`docs`目录下 > > gitbook build \[书籍路径] \[输出路径]，如果不指定参数，将默认使用项目目录下所有文件参与构建Book，并输出到\_book目录下 > > 需要注意的是，Wiki中的README.MD可以有 ### 书本查看 使用`serve`命令可在本地400端口查看书籍 ```shell gitbook serve Wiki ``` > 代码示例为：`Book` 相关内容全部放在Wiki目录下 > > gitbook serve \[书籍路径] \[output] ### 关联`GitHub Pages` * 首先确保此项目在`GitHub`上的仓库状态为公开 * 项目设置>`Pages`>`Branch`，设置分支及书籍`html`文件路径，本例中为`docs` ![image-20230527181536349](https://euclid-picgo.oss-cn-shenzhen.aliyuncs.com/image/202305271815515.png) * 查看`pages`，`url`为：https\://\[GitHub用户名].github.io/\[仓库名] ## `Gitbook`网页端服务 如果使用网页端的`GitBook`服务，可以不用安装`GitBook`。事实上安装`GitBook`会遇到很多苦难，所以直接使用`GitBook`网页端是一个很不错的选择。 ### 注册`GitBook`账号 网站上注册一个号，可能需要梯子。 ### 关联`GitHub` 关联`GitHub`后，可以将一本书与仓库绑定，我习惯的做法是，本地写内容，`Push`到`GitHub`上，`GitBook`会自动根据仓库变动，更新书本内容。 ### 查看书本 `GitBook`的优秀之处就是不需要向本地一样，构建书本、启动服务，直接会有一个网址，即为书本的网页阅读模式。[例如本书](https://euclid-jie.gitbook.io/gitbookdemo/) ### 注意事项 有些目录不是必须的，比如`_book`，不必`Push`至仓库，`GitBook`需要识别的`SUMMRAY.md`及其中的章节文件。 换言之，其实如果确定使用`GitBook+GitHub`的方式创建书本，只使用得到`gitbook init`。