github及gitbook入门
一、Github
创建个人主页
GitHub 为每一个用户分配了一个二级域名<user-id>.github.io，用户为自己的二级域名创建主页很容易，只要在托管空间下创建一个名为<user-id>.github.io的版本库，向其master分支提交网站静态页面即可，其中网站首页为index.html。
访问网址：https://panxin30.github.io/
创建项目主页
还可以为每个项目设置主页，项目主页也通过此二级域名进行访问。
访问地址：https://panxin30.github.io/book/
为项目启用项目主页很简单，只需要在项目版本库中创建一个名为gh-pages的分支，并向其中添加静态网页即可。也就是说如果项目的Git版本库中包含了名为gh-pages分支的话，则表明该项目提供静态网页构成的主页，可以通过网址http://<user-id>[.github.io/](http://.github.io/)<project-name>访问到。
创建gh-pages分支后，还需要在book这个仓库的settings中启用github pages
二、gitbook
1. 安装gitbook
参考：https://github.com/GitbookIO/gitbook/blob/master/docs/setup.md
2. 如果被墙，切换为淘宝镜像再安装
- 切换为使用国内速度较快的淘宝镜像。
npm config set registry=http://registry.npm.taobao.org -g
- 开始写书
方法一、直接在gitbook上新建space，然后点击integrations，整合github其中一个仓库，编辑gitbook会自动同步到github对应仓库。担心是gitbook被墙，在国内访问较慢。数据不会丢，因为用的github仓库存储。github上可以直接编辑 https://abu.gitbook.io/notes
方法二： 目标：在github新建一个仓库叫book，gitclone到本地，添加book.json，使用gitbook install book目录/ 安装插件，使用gitbook build book目录/构建静态资源，上传到panxin30.github.io或者book所在仓库的gh-pages分支（这就是github pages）。 缺点：不会自动更新，修改了书籍的源代码后需要再按照上面的操作来一次。前提是已经在本地安装了gitbook
方法三、使用github actions实现博客自动化部署 gitbook建立新书，关联到github仓库，给这个仓库添加actions，actions自动提交变更到gh-pages
以方法二为基础添加actions这一步
1. 设定GitHub Access Token
为了让GitHub Actions 能自动帮我们发布GitBook 成果到GitHub Pages，必须授权GitHub 操作我们的Repository。作法就是设定Access Token。
这里都是在GitHub 网页上操作，按照以下步骤即可：
2. 产生一个GitHub Personal Access Token：
- 点右上角帐号的头像->选择
Settings->左边列表选择最底下的Developer settings->下个页面的左边列表选择Personal access tokens。 - 点击
Generate new token按钮。 - 输入Token的描述，权限勾选
repo:status和public_repo两个项目。 - 点最下面的
Generate token按钮。 - 这时候页面上会显示一组Token，复制下来。注意！产生的Token内容只会在此时显示一次，之后无法再查到，如果忘记Token就只能重新操作产生一次。
3. 到Repository 将刚刚的Token 设定成Secret：
- 到想要自动发布的Repository ->选择
Settings->左边列表选则Secrets->点New secret按钮。 - 「Name」栏位填
GH_ACCESS_TOKEN，「Value」栏位贴上刚刚复制的Token。 - 点
Add secret按钮，设定就完成了。
4. GitHub Actions Workflow
万事俱备，只剩下设定GitHub Actions，让它能自动帮我们制书和发布到GitHub Pages。
回到资料夹，新增一个.github/workflows/build.yml档案：
$ mkdir -p .github/workflows
$ vi .github/workflows/build.yml
这里完全照抄即可，只需要把USER_NAME和USER_EMAIL设定更换成你的Git User Name和Email：
name: Build my gitbook and deploy to gh-pages
on:
workflow_dispatch:
push:
branches:
- master
jobs:
build:
name: Build Gitbook
runs-on: ubuntu-latest
steps:
# Check out the repo first
- name: Checkout code
uses: actions/checkout@v2
# Run this action to publish gitbook
- name: Publish
uses: tuliren/publish-gitbook@v1.0.0
with:
# specify either github_token or personal_token
github_token: 23e77fcdfda67b264737527285c2049f268c9f2a
# personal_token: ${{ secrets.PERSONAL_TOKEN }}
上面是一个GitHub Actions的设定档，称为一个「workflow」。里面用到官方的checkout action，这几乎是每个workflow的起手式。使用https://github.com/marketplace/actions/publish-gitbook 选择的一个gitbook相关的别人做好的镜像,负责将markdown档制成GitBook静态网站，并自动将网站档案commit到gh-pagesbranch。
5. 将Workflow 档推上GitHub，触发自动发布到GitHub Pages
将刚刚新增的workflow 档进行commit 和push：
$ git add .github/workflows/build.yml
$ git commit -m "add workflow file"
$ git push
回到GitHub Repository 页面，点「Actions」tab，会看到有一个workflow 任务被自动触发执行中：
等到执行完毕变成绿勾勾，会看到自动建立了gh-pagesbranch并commit GitBook静态网站的档案：
测试有没有自动更新
三、gitbook 插件
gitbook插件可以解决一些网站不太方便的地方，如侧边栏导航不能收缩，自带搜索不支持中文等。
插件安装、使用方法：
1、 在
book.json的plugins参数中添加插件名。
2、终端使用gitbook install来安装插件，或使用NPM命令来单独安装：npm install gitbook-plugin-插件名。
3、重新打包就能看见效果。
注意：
1、插件一定先要在book.json文件里面plugins中才能生效，如果只是安装了插件，而没配置的话是不会生效的。
2、gitbook命令安装慢，而且是全部插件都安装一遍，如果只安装一个插件的话建议使用NPM命令安装。
还有很多可用插件，具体如下：
- 信息框(
flexible-alerts) - 阅读统计（
pageview-count） - 侧边栏宽度可调节（
splitter） - 页脚版权（
page-copyright） - 打赏功能（
donate） - 分享当前页面（
sharing-plus） - 修改标题栏图标（
custom-favicon） - 复选框（
todo） - 显示图片名称（
image-captions） - 目录折叠（
toggle-chapters） - 分章节展示（
multipart） - 插入
Logo（insert-logo） Google分析（ga）- 返回顶部（
back-to-top-button） - 代码添加行号和复制按钮（
code） - 高级搜索，支持中文（
search-pro） - 添加
Github图标（github）
左侧目录可折叠
2.2.1 chapter-fold
支持多层目录，点击导航栏的标题名就可以实现折叠扩展。
在book.json的plugins参数中添加插件名：
{
"plugins": ["chapter-fold"]
}
然后使用npm install gitbook-plugin-chapter-fold命令安装插件。
注意：要想目录折叠，SUMMARY.md目录应该如下：
* [项目介绍](README.md)
* [tcp说明](doc/http/tcp/tcp说明.md)
* [udp说明](doc/http/tcp/udp/udp说明.md)
* [html](doc/html/readme.md)
* [HTML5-特性说明](doc/html/HTML5-特性说明.md)
如下写法会产生bug，导致CSS是收缩的，不能展开，效果如上面的动图：
* CSS
* [说明](doc/css/readme.md)
2.2.2 expandable-chapters
这个插件也是左侧目录折叠的插件，不同的是可以解决chapter-fold插件的bug，怎么写都会折叠目录
在book.json的plugins参数中添加插件名：
{
"plugins": [
"expandable-chapters"
]
}
安装命令：npm install gitbook-plugin-expandable-chapters
注意：这个插件也有问题，就是如下写法的，需要点击箭头才能展开收缩菜单：
* [tcp说明](doc/http/tcp/tcp说明.md)
* [udp说明](doc/http/tcp/udp/udp说明.md)
解决的办法是和chapter-fold插件一起用，互补一下各自的问题就完美解决了：
"plugins": [
"expandable-chapters",
"chapter-fold",
]
2.5 回到顶部按钮
在book.json的plugins参数中添加插件名和配置信息：
{
"plugins": [
"back-to-top-button"
],
}
使用npm install gitbook-plugin-back-to-top-button命令安装插件。
3.2 右上角添加github图标
在book.json的plugins参数中添加插件名和配置信息：
{
"plugins": [
"github"
],
"pluginsConfig": {
"github": {
"url": "https://github.com/zhangjikai"
}
}
}
然后使用npm install gitbook-plugin-github命令安装插件。
注意：
如果使用npm命令安装后报错GitBook doesn't satisfy the requirements of this plugin: >=4.0.0-alpha.0.
请使用gitbook install来安装.
或者npm uninstall gitbook-plugin-github卸载后，使用npm i gitbook-plugin-github@2.0.0安装，然后查看是否还报错。
3.3 edit-link在线编辑文件
book.json中插件名和配置信息：
{
"plugins": ["edit-link"],
"pluginsConfig": {
"edit-link": {
"base": "//github.com/yulilong/book/edit/master",
"label": "编辑此页面"
}
}
}
使用npm i gitbook-plugin-edit-link命令安装插件。
点击编辑按钮，即可跳转到github仓库在线编辑这个文件。
3.6 prism代码块颜色插件(测试没有通过)
插件地址：https://github.com/gaearon/gi...
此插件需要禁用gitbook自带的highlight插件。book.json中插件名和配置信息：
{
"plugins": ["prism", "-highlight"],
"pluginsConfig": {
"prism": {
"css": [
"prismjs/themes/prism-okaidia.css"
]
}
}
}
使用npm install gitbook-plugin-prism命令安装插件。
更多的颜色参考：https://github.com/gaearon/gi...
注意：代码块的语言标注比如JS,CSS,如果标注一个插件不认识的语言，在运行打包命令gitbook build .这个插件会报错，提示不认识这个语言，这里需要注意一下。