AsciiDoctor GitHub Pages Action

A GitHub Action that builds AsciiDoc GitHub Pages in your CI workflow. It recursively converts every adoc file to html, renaming resulting README.html to index.html then pushing all generated html and existing files to the gh-pages branch. If you don’t need anything fancy like Antora, this action might be the way to go to publish a simple AsciiDoc website. But if you need a more structured website, maybe Jekyll AsciiDoc QuickStart is for you.

After configuring the action, your GitHub Pages will be available at http://your-username.github.io/your-repository.

⚠️	Keep in mind that every time the action is executed, the gh-pages branch is wiped out. If you manually add anything to it, outside of the CI workflow, the content will be lost.

1. Live Demo

We taste our own medicine by publishing this repository to GitHub Pages.

2. Configuration

You have to just add the action to your yml workflow file and that is it. You can optionally customize the build by giving extra parameters to the action, which will be handed to the asciidoctor tool.

You can check a complete workflow file here. If you don’t want to use the GitHub Action interface and just copy that file to the same place inside your repository, it may work out of the box.

2.1. Troubleshooting

If you get the error "remote: Permission to git denied to github-actions[bot]", access Settings > Actions > General and select Read and write permissions.

2.2. Building an e-book

The action allows enabling the automatic generation of an ebook.pdf file from the AsciiDoc files. The pdf is pushed to the gh-pages branch too. To enable that, just add the following configuration:

pdf_build: true

A sample PDF ebook is available here.

2.3. AsciiDoctor Reveal.js Slides

You can also build AsciiDoctor Reveal.js slides with this action. That will generate a slides.html file into the gh-pages branch. You can use the following configuration for that:

• slides_build: boolean - enables building a slides.html file (default false)

• slides_main_adoc_file: string - defines the name of the AsciiDoc source file to build the slides (default 'README'). Do not include the file extension.

• slides_skip_asciidoctor_build: boolean - to enable skippig the build of regular html files using the asciidoctor command, if you just want to generate the slides (default false)

3. Other examples

If you want to check how to create a website from multiple AsciiDoc documents, check this sample repository. It’s only in Portuguese, but you can get the structure.

4. How the action works

The action is simple, but to show how you can create a website with multiple pages from different AsciiDoc files, the details are provided here in a separeted page. And realize the link above points to a: (i) adoc file when openning this page from the GitHub repository and (ii) html file when openning this page from the GitHub Pages.

5. FAQ

5.1. How can I configure a custom domain?

GitHub Pages need a CNAME file on the gh-pages branch. But on every action run, the gh-pages branch is wiped out. To make a custom domain work, just add the CNAME file in the root directory of your main or master branch instead and it will be copied over to the gh-pages branch automatically. If you have a source_dir configured, the CNAME file must be inside your configured source_dir.