Zenn
Open3

mdBook - GitHub Actions - GitHub Pages：静的サイトジェネレータとホスティングサービス

GitHub Actions
GitHub Pages
mdbook
spaspa

静的サイトジェネレータ

  • mdBook
  • GitBook
  • Jekyll
    などがある。マークアップ言語を本体に、さまざまな設定を書き加えることで構造化したり見た目をカスタマイズしたりして、立派なウェブサイトを構築することができる。

mdBook

GitBook

spaspa

ホスティング

GitHub Pagesに自動でデプロイするにはGitHub Actionsを使う。

peaceiris/actions-gh-pagesからの乗り換え

生のファイルと生成サイトとの関係

GitHub Actionsは、workflowが表現されたファイルのonの設定によってトリガーされる。ほかにも、GitHub Actionsの記述にはGitHub Actions Heroがわかりやすい。

main.yml
name: CI/CD
on: 
    push:
      branches:
      - master
      paths:
      - "src/**"
      - "book.toml"

「jobがstepごとにGitHubのサーバで動作する」。このとき、従来はたとえばデプロイ先のリポジトリのブランチを指定しつつpeaceiris/actions-gh-pagesをusesで呼び出して（デプロイしてもらっていた。ここを公式のactions/upload-pages-artifactやactions/deploy-pagesで代替できるようになった、というのが先の節に貼った記事の内容。
また、mdbook buildすら省略して、GitHub Actionsにビルドを任せるということもできる：peaceiris/actions-mdbook。

spaspa

mdBook

build

mdbook buildはプロジェクトフォルダで実行されなければならない。

➜  workflows mdbook build
2022-11-23 12:30:43 [ERROR] (mdbook::utils): Error: Couldn't open SUMMARY.md in ".../[プロジェクトフォルダ]/.github/workflows/src" directory
2022-11-23 12:30:43 [ERROR] (mdbook::utils):    Caused By: No such file or directory (os error 2)
➜  workflows cd ..
➜  .github cd ..
➜  [プロジェクトフォルダ] mdbook build    
2022-11-23 12:32:44 [INFO] (mdbook::book): Book building has started
2022-11-23 12:32:44 [INFO] (mdbook::book): Running the html backendnn

buildが成功するとbook/以下にウェブサイトの実装が生成される。例えば生のmdbook構成のほうのリポジトリにこれをpushするタイミングで、Pagesを設定したリポジトリにGitHub Actionsによる更新をかければいい。

カスタマイズ諸々