HonKit

開発用のドキュメントExcelなのつらいわーと思い、Markdownで書いたドキュメントを静的サイトとして出力できるVitePressのようなものを探していて、見つけたのがHonKitでした。

ちなみに↓HonKitのドキュメントもHonKitで作成されているので、どういう見た目で作成されるかの参考になります。

ドキュメントをPDFとして出力することも可能です（私の環境ではうまくいかなかったので、Chromeの印刷プレビューからPDF生成しています）。

シンプルですが最低限必要な機能はあり、カスタマイズもできそうです。
ドキュメントの脱Excel、かつGit管理したいというので使ってみることにしました。

# HonKitのインストール
npm install honkit --save-dev
# bookの作成
npx honkit init

package.jsonのscriptsにhonkitコマンドを追加して、

package.json

{
  "scripts": {
    "serve": "honkit serve",
    "build": "honkit build"
  }
}

npm run ...で表示確認ができるようになります。

# プレビュー表示
npm run serve
# 静的サイトのビルド（デフォルトでは_bookディレクトリ以下に生成される）
npm run build

GitHub Pages

せっかく静的サイトとして出力してくれるのだから、他の開発メンバーもインターネットからアクセスできるようにしたら便利。

というわけで、GitHub Pagesを使い、HonKitで生成された静的サイトを開発メンバー向けに公開してみることにしました。

リポジトリのSettings > Pagesから設定ができます。

GitHub Enterprise Cloudを使用している場合はアクセス制御が可能です。社内向けのドキュメントだとアクセス制御できるのが嬉しい

プライベートで公開されたサイトは、サイトの公開元のリポジトリの読み取りアクセスを持っている人だけがアクセスできます。
GitHub Pages サイトの可視性を変更する

GitHub Pagesの公開用として特定のリポジトリと、/（ルート）か/docsのフォルダを指定することもできますが¹、今回はGitHub Actionsを使ってビルド → デプロイが自動で実行されるようにしてみます。

GitHub Actions

Settings > Pages > Build and deploymentのSourceでGitHub Actionsを選択します。

Jekyllを使ったワークフローとstatic HTMLのワークフローを提案してくれるので、今回はstatic HTMLのスターターワークフローをベースに参考サイトのワークフローを参考にさせていただきつつ、cacheを利用し、HonKitのビルド → GitHub Pagesへのデプロイを行うワークフローを作成しました。

作成したワークフロー

今回作成したワークフローは以下になります。

masterブランチへのプッシュ（または手動でアクション実行）で起動します。

build.yml

# HonKitのビルドとGitHub Pagesへのデプロイを行う
name: build HonKit and deploy Pages

# ワークフローのトリガーイベント：
on:
  # masterブランチへのpush
  push:
    branches: ["master"]

  # Actionsタブから手動実行
  workflow_dispatch:

# GitHub Pagesへのデプロイを可能にするGITHUB_TOKENの権限をセット
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # ビルド
  build:
    # ランナー
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      # Node.jsのセットアップ
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version-file: 'package.json'
          cache: 'npm'
      # パッケージのインストール
      - name: Install dependencies
        run: npm ci
      # HonKitのビルド
      - name: build HonKit
        run: npm run build
      # .htmlに空白が多いのでフォーマット
      - name: format
        # 以下コマンドでprettierが起動するようにpackage.jsonで設定しています
        run: npm run format
      # アーティファクトのアップロード
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          # _book/以下をアップロード
          path: '_book/'

  # デプロイ
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

`actions/setup-node@v3`の設定について

使用しているアクションの内、actions/setup-node@v3について簡単に説明します。

Nodeのバージョン指定

今回はpackage.jsonを用いてNodeのバージョンを指定しています。

build.yml抜粋

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          # Nodeバージョン指定
          node-version-file: 'package.json'
          cache: 'npm'

node-version-file: 'package.json'とした場合、アクションは最初にvolta.nodeを検索し、なければengines.nodeを検索します。

余談ですが、以前あるフロントエンド開発で、package.jsonでNodeのバージョンを指定しなかったばかりに、開発者間のローカル環境で挙動が違う！ということがあったので、volta.nodeかengines.nodeでNodeのバージョンを指定したいと思うようになりました

package.json

{
  "engines": {
    "node": "18.15.0"
  },
  "volta": {
    "node": "18.15.0"
  }
}

Voltaって何？

VoltaはJavaScript コマンドラインツールを簡単に管理してくれます。

自分が使う時は、先述のようにプロジェクトでNodeのバージョンを固定したい場合に使用しています。

以下記事が分かりやすかったので、気になった方はぜひ。

「Node.jsのバージョン管理にVoltaを推したい」

cacheを使用する

cache: 'npm'と指定すると、依存関係のキャッシュと復元を行います。
デフォルトではキャッシュ機能がオフなので、指定する必要があります。

build.yml抜粋

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version-file: 'package.json'
          # 依存関係のキャッシュと復元を行う
          cache: 'npm'

ちなみにこのアクションでは node_modulesをキャッシュしていない のでそこは要注意です。

actions/setup-node@v3の内部ではactions/cacheというアクションが内部で使用されているということなので、そのドキュメントでNode - npmの項目を確認すると、どうやらnpm config get cacheで出力されるパスにあるnpmのキャッシュを使用しているようです。

また、actions/cacheのドキュメントではnode_modulesをキャッシュすることはおすすめしない、とあったので、今回はnode_modulesはキャッシュしていません。

ワークフローの完了

リポジトリトップのEnvironmentsにGitHub Pagesのデプロイ履歴へ遷移するリンクが追加されます。

各ジョブの詳細からは、各ステップで出力された結果を確認することも可能になります（エラー時には特に重宝します）。

こうして、https://xxxxx.pages.github.ioからHonKitで作成したドキュメントを閲覧することができます

今回はシンプルなワークフローでしたが、もっとGitHub Actionsを使いこなしたいなあと思う今日このです（LaravelプロジェクトをEC2にデプロイできるようにしたい）。

例えばmasterブランチの/docsを公開用と指定した場合、masterにpushされた際に/docsの静的サイトがGitHub Pagesとして公開されます。設定方法の詳細は「GitHub Pages サイトの公開元を設定する > ブランチからの公開」へ ↩