Gitbook相关注意事项

一、Gitbook文档编写环境搭建

1.1 gitbook环境搭建

1. 安装nodejs以及npm，参考nodejs与npm安装;

2. 安装proxychains-ng用于终端走代理，参考proxychain安装与使用。如果您不想安装proxychains-ng，可以参考terminal走代理进行设置;

3. npm install gitbook-cli -g安装gitbook-cli用于管理gitbook的版本;

4. gitbook fetch 3.2.3安装gitbook的3.2.3版本;

如果没有代理，那么可以将npm替换为国内源，参考npm替换国内源。

1.2 calibre安装

calibre提供了ebook-converter，用于将gitbook生成pdf。Ubuntu安装命令：sudo aptitude install calibre，Mac OS和Windows直接用安装包安装即可，Mac OS也可以使用brew cask install calibre安装。

1.3 编辑器选择

建议使用VS Code作为gitbook的编辑器，VS Code插件丰富且社区十分活跃，推荐使用koroFileHeader。

二、文档编写格式规定

2.1 标题

1. 以# 一级标题格式作为标题;

2. 以## 一、xxx格式作为正文一级标题;

3. 以### 1.x xxx作为正文二级标题;

4. 以#### 1.1.x xxx作为正文三级标题;

5. 禁止使用三级以上标题。

2.2 html特性的使用

html代码需要保持良好的缩进，便于日后修改。例如：

<table>
    <thead>
        <tr>
            <th>Bad</th>
            <th>Good</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>
                <code>
                // 应该足以满足任何情况！<br>
                c := make(chan int, 64)
                </code>
            </td>
            <td>
                <code>
                // 大小：1<br>
                c := make(chan int, 1) // 或者<br>
                // 无缓冲 channel，大小为 0<br>
                c := make(chan int)
                </code>
            </td>
        </tr>
    </tbody>
</table>

该段代码在gitbook中效果如下：

Bad	Good
// 应该足以满足任何情况！ c := make(chan int, 64)	// 大小：1 c := make(chan int, 1) // 或者 // 无缓冲 channel，大小为 0 c := make(chan int)

三、Markdown注意

1. 在每一级标题之间要空一行，否则gitbook pdf生成的pdf排版有问题，例如：

   ## 一、这是二级标题
   
   内容要与二级标题空一行。
   
   ## 二、这是第二个二级标题，内容要与上面空一行（not necessary,but recommend 😊 ）

2. 在描述键盘快捷键时，使用<kbd>Ctrl</kbd>标签将快捷键包裹，效果：Ctrl。

3. 在使用序号表示小节时，要在.后面空一格。当描述的内容属于这一小节时，内容要进行一个<kbd>Tab</kbd>的缩进，否则你所写的内容就会与小节处于同级。节与节之间不需要空一行。例如：

   1. 第一点
      第一点主要说明了。。。
   2. 第二点

4. 在markdown里面，没有换行的概念。只有通过一行空格来区分段。例如：

   这是一句话。
   尝试换行。

   以上写法会被markdown认为是一行，实际显示效果如下:

   这是一句话。尝试换行。

   如果想要换行，加一个空白行，例如:

   这是一句话。
   
   尝试换行。

5. front-matter用于表示markdown文件的matadata，格式如下:

   ---
   title: android内核编译
   date: 2020-11-20
   ---

   这个格式很好懂，就不多解释了，类似于ymal（冒号后面注意空一格，要求和yaml一样）。front-matter只能位于文件的最前端，所有注释都不能加在front-matter之前。例如：

   <!--
    * @Author: Rodney Cheung
    * @Date: 2020-04-24 15:16:29
    * @LastEditors: Sphantix Hang
    * @LastEditTime: 2020-11-10 15:00:19
    * @FilePath: /HandBook/environment/tools_deploy/ci/ci_deploy.md
   -->
   🙅 don't add any content before front-matter
   ---
   title: android内核编译
   date: 2020-11-20
   ---

6. 在标注代码块时，尽量带上代码的语言，这样markdown在渲染时会有高亮，看起来比较美观。例如:

   ```cpp

四、开发准则

1. 在clone前，推荐将公钥先添加到Github，避免每次push都需要输入账号密码，添加公钥的方法参考github添加公钥。
2. 在clone项目后，首先修改项目的配置。

    git config user.name <your name>
    git config user.email <your email>

   名字和邮箱应为github的primary email，如果使用全局的邮箱提交，在github上无法显示本人提交。

3. 在开发时，为了避免冲突，每次都应在master分支执行git pull，再切换自己的branch，并执行git merge master，合并master分支的修改。

4. 提交代码是，commit msg应为以下格式：

    Develop | <your commit msg> //添加新的文档
    Maintain | <your commit msg> //修改文档

5. 在提交之前，请在项目根目录使用gitbook pdf生成pdf文件，并至少检查修改部分是否显示正确。

五、关于SUMMARY.md的自动生成

经过研究，有现成的解决方案。下面简述步骤：

1. 安装gitbook-summary(需要nodejs)

   npm install -g gitbook-summary

2. 在目录中的README.md会作为该目录章节的链接（所以所有目录中介绍该目录内容的文件应该为README.md)

3. 前文讲述了front-matter，里面的title的值将作为SUMMARY.md中的标题名。（所以每个文件都应该指定front-matter，至少应该包含title字段）

4. 在Handbook根目录运行以下命令:

   book sm

该解决方案地址在这里，感兴趣的可以研究一下。