hexo + github page 搭博客 + gitbook

博客发布原理

撰写博客 --> hexo 渲染生成静态页面 --> 部署到 github page --> 用户访问

GitHub Pages 是由 GitHub 官方提供的一个免费的静态站点托管服务，
它让我们可以在 GitHub 仓库里托管和发布自己的静态网站页面。

Hexo 是一个快速、简洁且高效的静态博客框架，它基于 Node.js 运行，
可以将我们撰写的 Markdown 文档解析渲染成静态的 HTML 网页。

安装 Node.js

linux 有编好的二进制，下载解压即可。

wget https://nodejs.org/dist/v12.16.1/node-v12.16.1-linux-x64.tar.xz \
--no-check-certificate

解压后，将可执行文件软链接到某个环境变量能找到的位置，例如 /usr/local/bin。注意这里使用完整路径。
ln -s xxx/node-v12.16.1-linux-x64/bin/npm /usr/local/bin
ln -s xxx/node-v12.16.1-linux-x64/bin/node /usr/local/bin
ln -s xxx/node-v12.16.1-linux-x64/bin/npx /usr/local/bin

安装 hexo

如果没法科学上网的话，建议采用国内镜像加速。
npm config set registry https://registry.npm.taobao.org
npm install hexo-cli -g

hexo-cli 被放在了 node_xx/node_modules/，安装完成后会自动完成以下软链接
xxx/node-v12.16.1-linux-x64/bin/hexo ->
xxx/node-v12.16.1-linux-x64/lib/node_modules/hexo-cli/bin/hexo
建议和 npm node npx 一样在 /usr/local/bin 下面建一个软链接。

安装 git

git 的安装这里就不再详述了。
以上安装完成后以下命令均应当有相应的输出。

npm -v
node -v
hexo -v
git --version

配置 git，通过 ssh 协议访问 github，这样不用每次输密码。

git config --global user.name "username"
git config --global user.email "youremail"

# use ssh to connet the github
ssh-keygen -t rsa -C "your comments" #生成 ssh 秘钥对
cat ~/.ssh/id_rsa.pub #将公钥内容拷贝到 github

打开 github，在头像下面点击 settings，再点击SSH and GPG keys，New SSH key。
把上面 id_rsa.pub 的内容复制进去即可。

ssh -T git@github.com
应当显示校验成功。You've successfully authenticated

在 github 上新建一个仓库，仓库名必须是 github 用户名开头，.github.io 为后缀。github_user_name.github.io。

生成博客框架

在本机创建博客目录，初始化该目录，安装依赖包，通过 hexo 生成静态网页。

mkdir blog #博客根目录
cd blog
hexo init #初始化博客目录
npm install #安装所有依赖包
hexo g #等同于hexo generate，生成静态文件
hexo s #等同于hexo server，在本地服务器运行

打开 localhost:4000 查看博客效果
http://your_server_ip:4000

博客目录结构

.
├── _config.yml  #站点配置文件
├── db.json
├── node_modules #npm 包
├── package.json #npm 包信息
├── package-lock.json
├── public       #待部署的网页信息
├── scaffolds    #文章模板
├── source       #博客内容
└── themes       #博客网站主题

5 directories, 4 files

站点配置文件 blog/_config.yml
主题配置文件 blog/themes/xxx/_config.yml

写博客

新建博客，hexo new "title"
编辑博客
生成网页 hexo g
本地预览 hexo s
浏览器登录查看
部署到 github, hexo d

将博客部署到 github page

常用插件
hexo-deployer-git 部署
hexo-generator-feed RSS 订阅
hexo-generator-sitemap 站点地图

安装一个扩展，在博客根目录执行 npm i hexo-deployer-git。
在站点配置文件末尾添加如下配置项。

# Deployment
## Docs: https://hexo.io/docs/deployment.html
deploy:
  repo: https://github.com/usrname/usrname.github.io.git
  type: git
  branch: master

注意换成自己的用户名，之后 hexo d 就能将本地网页内容部署到 github 上。只要有互联网，都可以通过仓库名 username.github.io 来访问博客啦。

绑定域名

默认域名是 xxx.github.io，如果有其他域名需求可在各种云服务商上购买服务。在云服务商那里配置解析记录。然后在 github 博客仓库 settings 里找到 Custom domain 里填上域名。

这时候项目根目录应该会出现一个名为 CNAME 的文件。如果没有的话，打开本地博客的 /source 目录，新建 CNAME 文件。
然后在里面写上域名。最后运行 hexo g，hexo d上传到 github。

博客备份

本地博客目录文件大小还是很大的，关键的配置文件可以备份，方便在其他电脑上进行写作。

一个全新的博客本地文件目录如下
.
├── _config.yml
├── node_modules
├── package.json
├── package-lock.json
├── scaffolds
├── source
└── themes

4 directories, 3 files

在生成网页后会多出 public 目录以及 db.jason，可能会对其他文件进行修改。
├── db.json
├── public
在部署时还会生成
.depolyer_git 目录

主要的大目录是 node_modules 以及 public。前者可以用 git submodule 管理，或者进行压缩备份，后者用于部署的生成的网页信息，不是框架必须的，只需要备份余下的所有文件即可。本地测试 hexo init 初始化的全新博客目录发现，node_modules 占用了 40M，而整个博客项目才 41M。因此上述方案是可行的。可以在 .gitignore 中直接忽略相应的文件。

.DS_Store
Thumbs.db
db.json
*.log
node_modules/
public/
.deploy*/

安装主题

# download theme next
git clone https://github.com/iissnan/hexo-theme-next themes/next
# config
修改 _config.yml 里的 theme 字段为 next，默认主题是 landscape

因为会对主题做定制化修改，建议采用 submodule 的方式跟踪主题仓库，一方面方便回合上游的补丁，另一方面以后换电脑写博客也会方便很多。首先在 github 上 fork 一个主题仓库，作为 submodule 的仓库地址，然后执行

git submodule add https://github.com/xxx/hexo-theme-next.git ./theme/next

以后克隆博客仓库只需要执行
git clone --recursive-submodules xxx.git

或者
git clone xxx.git
git submodule init
git submodule update

If you already cloned the project and forgot --recurse-submodules, you can combine the git submodule init and git submodule update steps by running git submodule update --init. To also initialize, fetch and checkout any nested submodules, you can use the foolproof git submodule update --init --recursive.

记录一些 submodules 的命令
git config --global diff.submodule log
git config -f .gitmodules submodule.xxx.branch trace_branch
git config status.submodulesummary 1
git submodule sync --recursive
git submodule update --remote --rebase
git config push.recurseSubmodules check
git config push.recurseSubmodules on-demand
git submodule foreach 'git stash'
git submodule foreach 'git checkout -b feature-A

# 可以定义一些命令别名，省得记那么长的命令
$ git config alias.sdiff '!'"git diff && git submodule foreach 'git diff'"
$ git config alias.spush 'push --recurse-submodules=on-demand'
$ git config alias.supdate 'submodule update --remote --merge''

gitbook

GitBook是一个基于 Node.js 的命令行工具，可使用 Github/Git 和 Markdown 来制作精美的电子书。
在执行 gitbook serve 命令之后， gitbook 会从当前的原始内容中先生成 HTML 内容，然后启动一个内建的 web服务器，将生成的这些内容作为网站内容提供 HTTP 访问服务。

撰写书籍 --> gitbook 渲染生成静态页面 --> web 服务 --> 用户访问

命令行 CLI 的版本 2017 年之后已经很久没更新了。安装：

npm install gitbook-cli -g

// 初始化生成 README.md SUMMARY.md
// 其中 SUMMARY.md 是书籍的目录和排版
gitbook init

// 生成书籍
gitbook serve

...
Serving book on http://localhost:xxxx

// 在 SUMMARY.md 中添加章节，文件路径完整，支持导航栏层次结构管理，()为空则为导航栏占位符
# Summary

* [A](a/a.md)
    * [A1](a/a1.md)
        * [A1-1](a/a1-1.md)
            * [A1-1-1](a/a1-1-1.md)
    * [A2](a/a2.md)
* [B](b/b.md)
* [C](c/c.md)
* [D]()

gitbook serve 命令执行后，将生成 _book 目录，其中有 markdown 文件生成的对应的 HTML 文件。另外还有一个 gitbook 的目录，里面内容是 gitbook 自身的 js/css/图片/字体/插件等文件。在 build 完成之后，_book 目录下其实就已经有了整个数据的完整的生成文件，这些文件已经足够用于展示和发布。