bundler and CI (GitHub Actions)

Introduction

PureBuilder Simply is software designed for building growing websites, and it is not intended to be used by engineers as a documentation generator.
With PureBuilder Simply, you can build sophisticated websites with complex elements without a server‑side application, and differential builds help reduce build costs.
This is not necessarily what projects using tools like Hugo are looking for.

However, with some ingenuity, it is possible to use PureBuilder Simply as a documentation generator fully contained within a repository.

bundler

The most fundamental approach is to use Ruby bundler.
PureBuilder Simply itself does not use bundler, but since it is distributed as a RubyGems package, it can be used through bundler.

To keep everything fully contained within the repository, you need to specify a Ruby library as the document processor.
Here, we will assume the use of RedCarpet.

bundle init
bundle add pbsimply redcarpet

If you can require collaborators to install Pandoc (or Docutils), then you are no longer restricted in your choice of document processor.

To make the directory containing the Gemfile the document source root, add an option when installing the theme.
Of course, you can also choose not to use a theme and write everything yourself.

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

Even when installing a theme, you will need to make a small change to the configuration file.
The default output directory of the official theme is ../Build.
However, to keep everything within a single repository, the document build root must be located under the document source root.

outdir: ./_site

Make sure to create the output directory beforehand.

After that, you only need to generate the documentation through bundle exec.
For example, to generate documents in the article directory under ./_site/articles/:

bundle exec pbsimply article

This will work as expected.

Publishing with GitHub Pages

If you want to publish your site on GitHub Pages using PureBuilder Simply, the most recommended method is to set the output directory to ./docs and publish /docs from the default branch.

First, configure the output directory:

outdir: ./docs

Then, in your GitHub repository settings, go to “Pages, set”Build and deployment” -> “Source” to Deploy from a branch, and choose the /docs directory.

Publishing to GitHub Pages using GitHub Actions

If you absolutely must publish to the gh-pages branch using GitHub Actions, you can do so by writing a workflow that deploys static files.

This approach has little practical benefit.
After all, the HTML files are already generated, and simply publishing that directory is enough.
However, if you have a requirement to publish from the root of the gh-pages branch, or if using GitHub Actions is itself a requirement, this method works.

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

Building with GitHub Actions

If you want GitHub Actions to perform the build instead of building locally, you can write a workflow like the following.

Be sure not to forget placing the configured .pbsimply.yaml file at the root of the repository.
Here, we assume the outdir is ./out.

name: Build Site
on:
  push:
    branches: [ master ] # Change to match your main branch name
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # 1. Set up Ruby
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.4' # Ruby version to use
          bundler-cache: true # Automatically runs bundle install

      # 2. Set up Pandoc (only if using Pandoc)
      #- name: Set up Pandoc
      #  uses: r-lib/actions/setup-pandoc@v2

      # 3. Build with PureBuilder Simply
      # Specify directories to build according to your structure
      - name: Run pbsimply build
        run: |
          bundle exec pbsimply -f .
          bundle exec pbsimply -f articles
          # Copy static assets you want to include
          rsync -r images css favicon.ico ./out/

      # 4. Upload artifact
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: ./out # Directory specified in outdir of .pbsimply.yaml

  # Deploy to GitHub Pages
  # Make sure GitHub Pages is configured to deploy via 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

However, this approach is not elegant.
One of PureBuilder Simply’s strengths is its ability to perform dynamic generation and differential builds based on existing files.
If you regenerate the entire site every time, you lose much of the joy of using PureBuilder Simply.