GitHub Pages and Asciidoc

How to create GitHub pages using the AsciiDoc format.

Asciidoctor

Asciidoctor is a text processor and publishing toolchain for the AsciiDoc format, made using the Ruby programming language.

A way to run Asciidoc without having to install anything locally, namely the Ruby dependencies, is via docker. The https://hub.docker.com/r/asciidoctor/docker-asciidoctor/ image contains an Asciidoc installation.

The following command converts all AsciiDoc files in the root folder to the HTML format, placing the produced files in the out folder.

docker run --rm -u $(id -u):$(id -g) -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor -D ./out *.adoc

GitHub Pages

By default, [GitHub Pages] use Jekyll to produce the viewable HTML. However it is possible to use alternative content producing mechanisms via GitHub Actions.

First, enable GitHub Pages on the repository. Then, on the “Build and deployment” section select “GitHub Actions” for the “source”. This results in GitHub not automatically running any pages deployment process.

Second, create a publishing GitHub Actions workflow. The following workflow is based on the one present in https://github.com/asciidoctor/jekyll-asciidoc-quickstart/blob/main/.github/workflows/publish.yml.

# Based on https://github.com/asciidoctor/jekyll-asciidoc-quickstart/blob/main/.github/workflows/publish.yml
name: Publish to GitHub Pages
on:
  push:
    branches: [main]
  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:
concurrency:
  group: github-pages
  cancel-in-progress: false
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: $
    steps:
    - name: Checkout
      uses: actions/checkout@v4
    - name: Configure Pages
      id: pages
      uses: actions/configure-pages@v5
    - name: Generate Site (generated files will be in the `out` folder)
      run: ./build.sh
    - name: Upload Artifacts, located on the `out` folder.
      uses: actions/upload-pages-artifact@v3
      with:
        path: out
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

The build.sh is just a script file containing the commands to build the HTML files from the AsciiDoctor files.

docker run --rm -u $(id -u):$(id -g) -v $(pwd):/documents/ asciidoctor/docker-asciidoctor asciidoctor -D ./out *.adoc