mdbookをGitHub PagesにActionsから自動デプロイする

mdbookで生成したドキュメントを、GitHub ActionsからGitHub Pagesに自動デプロイする方法を整理します。

はじめに
mdbookをGitHub ActionsからGitHub Pagesに自動デプロイする
おわりに
参考

はじめに

mdbookはmarkdownからドキュメントを生成できるRust製のツールです。特にRust界隈では、デファクトと言えるドキュメント生成ツールでしょう。

今回はこのmdbookを使って、GitHub ActionsからGitHub Pagesに自動デプロイする方法をまとめます。

mdbookをGitHub ActionsからGitHub Pagesに自動デプロイする

最終的なコードは下記に配置していますので、こちらも参照ください： github.com

mdbookのインストール

mdbookはcargo経由でインストールできます。

cargo install mdbook

あるいは、mdbookのreleaseページからコンパイル済みのバイナリを直接ダウンロードすることも可能です： Releases · rust-lang/mdBook · GitHub

cargoがインストールされていない面倒な環境でも、バイナリをダウンロードしてPATHを通せばすぐにmdbookを使うことができます。

その他のインストール方法は、mdbookのインストールドキュメントをご覧ください。

mdbookドキュメント作成

ドキュメント作成は、initコマンドでテンプレートプロジェクトを作成することからはじめます。

mdbook init

initすると、下記のファイルが生成されます。

$ tree
.
├── book
├── book.toml
└── src
    ├── SUMMARY.md
    └── chapter_1.md

3 directories, 3 files

あとはこれらのmarkdownをベースに、ドキュメントを更新していきます。基本的にはsrc/SUMMARY.mdで全体の構成を記述し、各markdownファイルへのリンクを埋め込んでいく形になります。

ローカルでドキュメント生成するには、buildコマンドを使います。

mdbook build

book/フォルダ配下にhtmlファイルが生成されるので、index.htmlをブラウザで開けばローカルで生成ドキュメントを確認することができます。

GitHub Actionsの実装

ドキュメントを書いたら、これを自動でGitHub Pagesにデプロイするよう以下のようなActions workflowを用意します：

name: Deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout sources
        uses: actions/checkout@v2

      - name: Setup mdBook
        uses: peaceiris/actions-mdbook@v1
        with:
          mdbook-version: 'latest'

      - name: Build docs
        run: |
          mdbook build

      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./book