Publish to GitHub Pages

Antora is designed to create sites that run anywhere, whether it be on a static web host or the local filesystem. However, some hosts offer “features” that mess with Antora’s output. GitHub Pages is one of those hosts.

Jekyll and underscore files

By default, GitHub Pages runs all files through another static site generator named Jekyll (even if your repository is not set up to use Jekyll). Since Antora already produces a ready-made site, there’s absolutely no need for this step. But it’s more than just the wasted effort.

Jekyll has the nasty side effect of removing all files that begin with an underscore (_). Why is this a problem? By default, Antora puts UI files in a folder named _. It also places images inside the folder named _images. When Jekyll comes through, it wipes out these folders. As a result, you get no UI and no images.

.nojekyll

Fortunately, there’s a way to disable this “feature” of GitHub Pages. The solution is to add a .nojekyll file to the root of the published site (i.e., the output directory configured in your playbook).

The presence of the .nojekyll file at the root of the gh-pages branch tells GitHub Pages not to run the published files through Jekyll. The result is that your Antora-made site will work as expected.

Let’s look at two ways to create the .nojekyll file when you run Antora.

Touch the file manually

One way to add this file is to touch the .nojekyll file in the output directory after Antora runs, but before committing the files to GitHub Pages. For example:

$ touch build/site/.nojekyll

Fortunately, there’s way to do this without having to run a separate command.

Use the supplemental UI

To avoid the need for the extra command, the other way to do it is to inject the file using Antora’s supplemental UI feature. To do so, add the following supplemental_files block under the ui category in your playbook file:

Example 1. antora-playbook.yml that adds .nojekyll file using supplemental UI

ui:
  bundle:
    url: <url-of-bundle-goes-here>
  supplemental_files:
  - path: ui.yml
    contents: |
      static_files:
      - .nojekyll
  - path: .nojekyll

This configuration defines files from memory. The first file, ui.yml, tells Antora which files to promote to the root of the site (outside the UI folder) using the static_files key. The second file, .nojekyll, writes to the root of the published site. Since the contents key is absent, Antora will create an empty file (the equivalent of the touch command from above).

Using GitHub Actions

If your playbook repository is hosted on GitHub, you can configure a GitHub Actions workflow to build and publish your site to GitHub Pages. The benefit of using GitHub Actions is two-fold. First, you don’t have to worry about copying the published files to the gh-pages branch for publishing. Second, you don’t have to worry about the .nojekyll file since the action handles it for you. Let’s get started!

Example 2 shows an example of a GitHub Actions workflow that uses the latest stable release of Antora to build and publish your site to GitHub Pages. This workflow assumes that the name of the default branch of your playbook repository is main, that the name of your playbook file is antora-playbook.yml, and that Antora is configured to publish the files to the build/site directory. If your site uses different settings, you’ll need to update the values in the workflow file accordingly.

Example 2. .github/workflow/publish.yml builds the Antora site and deploys it to GitHub Pages using GitHub Actions

name: Publish to GitHub Pages
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Install Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
    - name: Install Antora
      run: npm i antora
    - name: Generate Site
      run: npx antora antora-playbook.yml
    - name: Publish to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: build/site

As Example 2 shows, you can install and invoke Antora directly from the workflow. This workflow installs a specific release of Antora (both the CLI and site generator packages) and then uses the Antora CLI in the workflow. The workflow then uses the peaceiris/actions-gh-pages action to publish the site, along with the required .nojekyll file, to GitHub Pages.

To install and use a different verson of Antora, append a version to the package name, such as antora@3.0.1.

Let’s now take this a step further by adding the Antora Lunr Extension to incoporate a search widget in the built site. First, you need to update your playbook repository and UI to meet the minimum requirements of the Antora Lunr Extension as described in the README for that project. Once that’s done, return to the GitHub Actions workflow and configure it to install the extension at the same time it installs Antora. The result is shown in Example 3.

Example 3. .github/workflow/publish.yml includes the Antora Lunr Extension

name: Publish to GitHub Pages with Lunr Search Extension
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout repository
      uses: actions/checkout@v2
    - name: Install Node.js
      uses: actions/setup-node@v2
      with:
        node-version: '16'
    - name: Install Antora and the Antora Lunr Extension
      run: npm i antora @antora/lunr-extension
    - name: Generate Site
      run: npx antora antora-playbook.yml
    - name: Publish to GitHub Pages
      uses: peaceiris/actions-gh-pages@v3
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: build/site

To install and use a different verson of the Antora Lunr Extension, append a version to the package name, such as @antora/lunr-extension@1.0.0-alpha.5.