国芯 AI 开放平台 使用 Gitbook 进行文档协作教程

1.准备工作

1.1 申请 Alicode 账号

到这里注册 Alicode 账号，或者直接登录，之后生成 ssh key（如何生成具体百度），到个人中心添加自己的 ssh key 公钥 ，以获取推送免密功能。

因为该仓库是私有的，需要先加入到项目才有编辑权限，已加入到公司账号组且组权限为master的同事，可以自行加入到8010doc项目，否则联系我或者其他具有组master权限的同事加入到8010doc项目。所有人的项目权限原则上都为developer，避免在publish分支上进行误push操作。权限参考 alicode 官方文档。

1.2 安装Git/Gitbook：

#git
sudo apt-get install git


#gitbook 依赖于Nodejs，所以先安装Nodejs
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs
#检查nodejs是否安装成功
node -v

#安装gitbook
sudo npm install -g gitbook gitbook-cli

#检测gitbook是否安装成功
gitbook --version

最后到 https://legacy.gitbook.com/editor 下载 Editor 手动安装 editor。

2.编辑文档

编辑文档约法三章：

• 禁止使用 rebase 命令合并
• 禁止在 publish 分支进行修改、push，如果想看文档最新的内容，可在 publish 分支进行 pull 操作
• master 分支 push 之前，先执行 pull 操作，解决冲突并合并后再进行 push

2.1 获取文档仓库

git clone ${url}

2.2 使用 Visual Studio Code 编辑文档（推荐）

2.2.1 关于 Markdown 与 VS Code

Markdown 使用一种通用型的轻量级标记语言，以其语法简介、浏览器原生支持的特性受到开源业界的欢迎，是很多开源项目的README和开发文档的默认格式。Markdown文档本质上来说是一种带有特定标记的文本文档，可以用任何文本编辑器如NotePad、gEditor、vim、Emacs等进行撰写或编辑。Gitbook正是基于Markdown文件来组织文档内容。

Visual Studio Code 是 Microsoft 公司开发的跨平台的现代编辑器，也被很多人当作轻量级的IDE使用。VS Code原生支持Markdown文件编辑，提供Markdown标签高亮着色、错误提示等准IDE功能，更重要的是提供了对Markdown文档的实时预览。这使得使用VS Code代替老旧的Gitbook Editor 来撰写 Gitbook 文档成为可能。

为了快速使用 VS Code 撰写 Gitbook 文档，你需要收入学习 Markdown 的语法，了解如何通过标签进行文本编辑、插入图片/表格/超链接等技巧。

由于VS Code的官方下载地址被公司内网屏蔽，现提供 vscode 下载地址供公司内部使用：

• ubuntu
• macos
• windows

2.2.2 Gitbook 文档结构

Gitbook 文档的组织关系通过SUMMARY.md来体现，同时Gitbook会把SUMMARY.md渲染成位于文档左侧的目录树，进而完成导航。

应当注意到如下几点：

• SUMMARY.md使用的是标准的Markdown链接语法
• 每个标题要链接到的内容可空，仅作为目录使用
• 目录的层级结构只是一种逻辑结构，与其物理存储层级无关

2.2.3 使用 VS Code 编辑文档

新建目录

• 在SUMMARY.md相应的位置和层级添加一个链接条目
• 如果该目录链接到具体的内容，那么新建一个MD文档，并将相对地址填入到链接的括号中，否则，括号内容为空

插入图片

• 将需要插入的图片放置到一个存储位置，如assets文件夹,如果没有，则新建文件夹

按照MD语法插入一个图片引用，将图片的绝对位置填入到括号中，如

![](/http://www.wenjiangs.com/wp-content/uploads/2021/docimg30/188-ds3hkctqvkb.png)

预览文件

编辑单个MD文件时可点击右上角带有放大镜图标的预览按钮，实现实时预览。

其他内容如标题/表格/超链接等内容青参见标准的Markdown语法。

2.3 使用 Gitbook Editor 编辑文档

运行Gitbook Editor，通过菜单Gitbook->Open，导航到Clone的仓库目录，打开

2.3.1 编辑文件

直接在打开的文档中进行需改即可。

2.3.2 新增目录和文件

在左侧目录树中需要的地方右击，添加文件即可

2.3.3 保存更改

注意编辑器的左上角有指示当前所处的分支，请确保自己处于Primary分支(master分支)

编辑完成后，点击右上交的保存按钮保存，gitbook 会自动 commit 更改到本地仓库。注意不要点击最右侧的同步按钮（点了也没用）！

3.预览文档

在文档的仓库目录中执行以下命令可以预览效果：

#安装插件
gitbook install
gitbook serve

使用浏览器打开 http://localhost:4000 预览效果

4. 提交更改

当确定修改没有问题后，将更改提交至远程仓库。首先在仓库目录执行 git pull，同步远程仓库的更改

如果有冲突，解决冲突后再合并提交，一般情况下 SUMMARY.md 会有冲突，因为 SUMMARY.md 作为目录文件，肯定会随着新文件内容的增加而被不同人修改，此时，保留别人和自己的更改再合并提交就好。执行 git push，将本地更改推送到远程仓库：

此时，只是将更改推送到远程仓库的 master 分支，并不会触发文档在线更新，可通知具有管理员权限的同事将 master 分支合并到 publish 分支，以更新在线文档。