BioErrorLog Tech Blog

試行錯誤の記録

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

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

peaceiris/actions-gh-pagesを使ってGitHub Pagesにデプロイしています。

このactions workflowが実行されると、gh-pagesという名前のbranchに、生成されたhtml群がpushされます。

mdbookのwikiには他のやり方も記載されているので、必要に応じてそちらも参照ください。

GitHub Pagesの設定

最後に、branch gh-pagesからGitHub Pagesをデプロイするよう設定を変更します。

  1. GitHubレポジトリの上タブからSettingsをクリック
  2. 左タブからPagesをクリック
  3. Build and deploymentセクションで、Branchgh-pagesに設定
    (指定フォルダはrootのまま)
  4. Saveをクリック

SettingsタブからGitHub Pages設定を行う

これで、mdbookで生成したドキュメントがGitHub Pagesにホストされるようになります。

GitHub PagesのURLパターンは https://<user name>.github.io/<repository name>/ です。

例: https://bioerrorlog.github.io/mdbook-example/

GitHub Pagesにデプロイされたmdbook生成ドキュメントの例

最終的なコードはこちらに置いています(再掲)。 github.com

おわりに

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

Markdownから簡単にhtml形式のちゃんとしたドキュメントを生成&ホストできるので、とても便利ですね。

どなたかの参考になれば幸いです。

[関連記事]

www.bioerrorlog.work

www.bioerrorlog.work

www.bioerrorlog.work

参考

GitHub - peaceiris/actions-mdbook: GitHub Actions for mdBook (rust-lang/mdBook) ⚡️ Setup mdBook quickly and build your site fast. Linux (Ubuntu), macOS, and Windows are supported.

GitHub - peaceiris/actions-gh-pages: GitHub Actions for GitHub Pages 🚀 Deploy static files and publish your site easily. Static-Site-Generators-friendly.

Automated Deployment · rust-lang/mdBook Wiki · GitHub

GitHub - rust-lang/mdBook: Create book from markdown files. Like Gitbook but implemented in Rust

Publish the mdBook to gh-pages workflow as a separate action · Issue #1090 · rust-lang/mdBook · GitHub

Continuous Integration - mdBook Documentation