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
コマンドを追加して、
{
"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
のフォルダを指定することもできますが1、今回はGitHub Actions
を使ってビルド → デプロイが自動で実行されるようにしてみます。
GitHub Actions
Settings > Pages > Build and deployment
のSourceでGitHub Actions
を選択します。
Jekyll
を使ったワークフローとstatic HTML
のワークフローを提案してくれるので、今回はstatic HTMLのスターターワークフローをベースに参考サイトのワークフローを参考にさせていただきつつ、cacheを利用し、HonKit
のビルド → GitHub Pages
へのデプロイを行うワークフローを作成しました。
作成したワークフロー
今回作成したワークフローは以下になります。
masterブランチへのプッシュ(または手動でアクション実行)で起動します。
# 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
のバージョンを指定しています。
- 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のバージョンを指定したいと思うようになりました
{
"engines": {
"node": "18.15.0"
},
"volta": {
"node": "18.15.0"
}
}
Voltaって何?
VoltaはJavaScript コマンドライン ツールを簡単に管理してくれます。
自分が使う時は、先述のようにプロジェクトでNodeのバージョンを固定したい場合に使用しています。
以下記事が分かりやすかったので、気になった方はぜひ。
cacheを使用する
cache: 'npm'
と指定すると、依存関係のキャッシュと復元を行います。
デフォルトではキャッシュ機能がオフなので、指定する必要があります。
- 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 サイトの公開元を設定する > ブランチからの公開」へ ↩