Hello Hexo & Travis !

Development 2018-12-29

静态网站生成器

GitHub static-site-generator 主题下 Node.JS 架构 star 前三的项目中，Hexo 生态最完善：

包括中文在内的多语言官网
使用文档不但每页开篇有视频讲解，简体中文视频直接托管在 Bilibili
插件、主题的搜索引擎更是方便，接地气的国人作品也很多

官网一番学习之后，发现起步比较简单：

npm install hexo --global

hexo init my_pages

git init
git checkout --orphan hexo

随后又在官网搜了一个简洁、美观、强大、易用的主题模板 Matery。

持续集成、持续部署

最后一顿 Google，入门了近几年开源界最流行的 Travis CI，它的配置文件 .travis.yml 看起来像 Dockerfile，但更自然：

branches:
  only:
    - hexo

language: node_js
node_js:
  - lts/*
cache:
  directories:
    - node_modules

before_install:
  - export TZ=${TIME_ZONE}
install:
  - npm install
script:
  - npm run ${SCRIPT}
deploy:
  provider: pages
  on:
    branch: hexo
  skip_cleanup: true
  local_dir: ${FOLDER}
  fqdn: ${DOMAIN}
  token: ${TOKEN}
  target_branch: ${BRANCH}

上述命令行脚本中的环境变量可在 Travis CI 项目配置页设置，示例如下：

变量名	示例值	释义	备注
TIME_ZONE	Asia/Chongqing	系统时区
SCRIPT	build	构建脚本名
FOLDER	public	网页生成器的输出目录
DOMAIN	example.com	自定义域名
TOKEN		Git 平台个人访问令牌	https://github.com/settings/tokens/new
BRANCH	master	GitHub Pages 目标分支

新版个人网站初步落成！~

开源项目 API 文档生成

既然 Travis CI 配置脚本可以用环境变量变得灵活，那基于 JSDoc、ESDoc 之类的开源项目生成 API 文档站也可照搬以上方法了：

再也不用在本地 Git precommit 钩子上执行文档生成脚本了，加快提交速度
把生成的文档放在独立的 gh-pages 分支，让 master 分支只放源码，提交记录更清爽
用 git push --force 也让文档站分支不保留不必要的提交记录，仓库体积最小化

但是，Travis 的 Windows 环境尚处测试阶段，我实测时出现“失败但无报错详情”的 bug，只好让 Puppeteer-IE 改用 Azure Pipeline：

trigger:
  - master

pool:
  vmImage: 'vs2017-win2016'

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '8.x'
    displayName: 'Install Node.js'

  - bash: |
      npm install
      npm run build
      cd ${DOC_FOLDER}
      git init
      git config user.name ${GIT_USER}
      git config user.email ${GIT_EMAIL}
      git add .
      git commit -m "${GIT_MESSAGE}"
      git push --force --quiet https://${GIT_TOKEN}@${GIT_URI}.git master:${GIT_BRANCH}
    displayName: 'npm install & build Document'