bundlerとCI (GitHub Actions)

はじめに

PureBuilder Simplyは成長していくウェブサイトを構築するために作られたソフトウェアであり、エンジニアがドキュメントを生成するために使うことを想定していません。 PureBuilder Simplyであれば複雑な要素を持つ高度なウェブサイトを、サーバーサイドアプリケーションなしに構築することができ、差分生成によってビルドコストを下げることができます。これは、例えばHugoを使うプロジェクトが求めているものではないでしょう。

しかし、やり方を工夫することでPureBuilder Simplyをリポジトリに閉じたドキュメント生成ソフトウェアとして利用することは可能です。

bundler

最も基本となるのはRuby bundlerを使うことです。 PureBuilder Simply自身はbundlerを使用しませんが、RubyGemsで公開されているパッケージなので、bundlerで使うことは可能です。

リポジトリに完全に閉じた状態にするためには、ドキュメントプロセッサにRubyのライブラリを指定する必要があります。ここでは仮にRedCarpetを使うことにしましょう。

bundle init
bundle add pbsimply redcarpet

共同作業者にPandoc(あるいはDocutils)をインストールすることを要求できるのであれば、ドキュメントプロセッサの制約はなくなります。

リポジトリの(既にGemfileのある)ディレクトリをドキュメントソースルートにするため、テーマのインストールにオプションをつけます。もちろん、テーマを使わずに自分で書くこともできます。

bundle exec pbsimply-init -sf -t redcarpet/init322

テーマをインストールした場合でも設定ファイルに少し変更が必要です。公式テーマのデフォルトの出力先は../Buildになっています。しかし単一のリポジトリに閉じるためにはドキュメントソースルートの下にドキュメントビルドルートが必要です。

outdir: ./_site

出力先ディレクトリはあらかじめ作っておきましょう。

あとはbundle execを介してドキュメントを生成するだけです。例えばarticleディレクトリ内のドキュメントを./_site/articles/以下に生成するならば

bundle exec pbsimply article

で機能します。

GitHub Pagesで公開する

PureBuilder Simplyを使ってGitHub Pagesでサイトを公開したい場合、最も推奨される方法は出力先ディレクトリを./docsにし、デフォルトブランチの/docsを公開することです。

まずは./docsに出力されるようにします。

outdir: ./docs

続いてGitHubのリポジトリ設定でPagesから “Build and deployment” > “Source” を Deploy from a branch とし、ディレクトリを /docs に設定します。

GitHub Actionsを使ってGitHub Pagesに公開する

ただしどうしてもGitHub Actionsを使ってgh-pagesブランチに公開したいのであれば、静的ファイルを公開するGitHub Actionsを書くことで実現できます。

この方法は実質的な意味はほとんどありません。なぜならば既に生成されているHTMLファイルが存在しており、そのディレクトリを公開するだけで実現できるのですから。しかし何らかの理由でgh-pagesブランチのルートを公開する方法を採用したい場合や、GitHub Actionsを使うこと自体が要件である場合にはこの方法を使うことができます。

name: GitHub Pages

on:
  push:
    branches: [master]

jobs:
  deploy:
    runs-on: ubuntu-latest
    concurrency:
      group: ${{ github.workflow }}-${{ github.ref }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

GitHub Actionsを使ってビルドを行う

手元でビルドせず、ドキュメントのビルド自体をGitHub Actionsで行いたい場合、次のようなactionを書くことで実現できます。

リポジトリのルートに設定済みの.pbsimply.yamlファイルを置くのを忘れないようにしましょう。ここではourdirは./outであると想定しています。

name: Build Site
on:
  push:
    branches: [ master ] # 自分のメインブランチ名に合わせて変更
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Rubyのセットアップ
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.4' # 使用するRubyのバージョン
          bundler-cache: true # bundle install を自動実行

      # 2. Pandocのセットアップ (Pandocを使う場合のみ)
      #- name: Set up Pandoc
      #  uses: r-lib/actions/setup-pandoc@v2

      # 3. PureBuilder Simply によるビルド
      # ディレクトリ構成に合わせてビルドするディレクトリを指定
      - name: Run pbsimply build
        run: |
          bundle exec pbsimply -f .
          bundle exec pbsimply -f articles
          # 組み込みたい静的なアセットをコピーする
          rsync -r images css favicon.ico ./out/

      # 4. アーティファクトの保存
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: ./out # .pbsimply.yaml の outdir で指定したディレクトリ

  # GitHub Pagesのデプロイ
  # Pagesの設定でGitHub Actionsでデプロイするようにしておかないと失敗する
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

ただしこの方法はエレガントではありません。 PureBuilder Simplyはビルドされているファイルに基づいた動的な生成や、差分生成ができることが魅力のひとつです。毎回全体を生成し直すのであれば、PureBuilder Simplyを使う喜びは半分も感じられないでしょう。