Building an Antora Site II

Part 2: Launching an Antora website with GitHub Pages (A tutorial… based on personal experience)

SpecterLab Server Documentation

Please visit (https://specterhead.github.io) for the documentation that inspired this post.

A tutorial… based on personal experiences

Now that we have been creating, editing, and updating our Antora site pages locally, it is time to launch the site.

GitHub pages provides a free and accessible website that hosts directly from your GitHub repository. Using a repository allows you to host not only the webpages, but also provides a place for you to store your source files. For an Antora build, this is particularly useful because the source files and file structure are very important for each iteration of your project.

Let’s begin!

  1. To make and publish a user GitHub Pages site, you need to have a repository with the naming convention: <username>.github.io.

  2. Set the publishing source of your repository.

For this tutorial, we will be working out of the main branch, using the root as our webpage starting point. In your respository Settings, under GitHub Pages, save the Source as ‘master’ and the Folder as / (root).

Side note: The only option for the repository publishing source is either root or /docs. You cannot use a unique folder name. Since the /docs folder will be holding the Antora source files, the root is best used to build the website.

  1. In the repository, create a /docs folder. Here you can add the source code of your Antora project, that is, the Antora-specific file structure we created in the previous tutorial.

For example:

Repository root
└── docs folder
    ├── antora.yml
	├── ui-bundle.zip
    └── modules folder
        └── ROOT folder
            └── pages folder
                └── index.adoc
        └── content folder
            ├── nav.adoc
            └── pages folder
                └── <content_files>.adoc

You will notice a ui-bundle.zip in this folder, but don’t worry, that also comes up later.

  1. Now that you’ve moved our local Antora documents to a GitHub repo, you will need to update the antora-playbook.yml file with the correct file paths to pull from this repository.
    • Update the URL to: https://<username>.github.io
    • Make sure your Sources URL directs to your GitHub repository (for example: https://github.com/<username>/<username>.github.io)
    • The branches key is master and start_path is docs

3.a. While we’re updating the playbook file, we will also need to update the UI source.

  1. Follow the UI URL file path from the Antora Docs page. This will download a compressed file ui-bundle.zip to your computer.
  2. Upload this uncompressed file to your repository, and place just inside the /docs folder, as noted above.
  3. Change the playbook UI URL file path to: https://github.com/<username>/<username>.github.io/blob/master/docs/ui-bundle.zip?raw=true

3.b. We also need to add a supplemental UI section to the playbook file. Just under the UI URL, add:

supplemental_files:
- path: ui.yml
  contents: |
    static_files: [ .nojekyll ]
- path: .nojekyll 

See the section “Some strange problems I encountered along the way” for an update to this addition.

  1. Upload your newly updated playbook file to the root of your repository.

GitHub Pages uses Jekyll by default. Unfortunately, Jekyll and Antora process files differently (see this link for more detail). To address these differences, there are a few specific steps that you need to follow in order to build the Antora pages correctly.

Hence the supplemental file in step 3.a.

  1. In your GitHub repository root, create an empty file called .nojekyll. This file is also created in step 8, but the GitHub Pages says to create this empty file, “then follow your static site generator’s instructions to build your site locally” (Step 8).

  2. Run a local build with your updated repository files. If you are working out of GitHub Desktop, this would first entail refreshing (fetch & merge) your local repository files. Then run the local antora-playbook.yml file in the command line interface. For example, in my system:

C:\Users\<user>\docs-site>
cmd
antora generate --fetch antora-playbook.yml 

As usual, this creates a build folder populated with local HTML files of your Antora site.

  1. Since we are not using Jekyll, GitHub will be looking for an index.md (or index.html!) file in the root of the repository. This file can be a placeholder—or redirect—file pointing to the contents of your built webpages. You can use the following template:
<!DOCTYPE html>
<meta charset="utf-8">
<link rel="canonical" href="https://<username>.github.io/<build file path>/index.html">
<script>location="<build file path>/index.html"</script>
<meta http-equiv="refresh" content="0; url=<build file path>/index.html">
<meta name="robots" content="noindex">
<title>Redirect Notice</title>
<h1>Redirect Notice</h1>
<p>The page you requested has been relocated to <a href="<build file path>/index.html">
    https://<username>.github.io/<build file path>/index.html</a>.</p>
  1. Now, push the built HTML site folder contents (docs-site/build/site/<all contents>) to your repository.

Your GitHub repo should now contain (in no particular order):

/root
	/_
	/<folder containing built HTML pages>
	/docs
	antora-playbook.yml 
	.nojekyll
	README.md
	index.html
	404.html
	sitemap.xml

Congratulations! Upon refreshing, and waiting anywhere between 30 seconds and 20 minutes (GitHub needs time to build the site) you have launched an Antora SSG to GitHub Pages at https://.github.io!

Some strange problems I encountered along the way

CSS: When the Antora site was first hosted through GitHub pages, the pages displayed in plain HTML. If this happens, make sure the page headers contain the correct file path to the CSS. This GitHub community post has a great explanation.

Also, it does not seem to matter if the GitHub Languages bar shows CSS & HTML. As long as the CSS file path is correct the pages will display properly.

Supplemental_file: When re-running future builds of the HTML pages, I was getting a command line error saying, error: configuration param 'supplemental_files' not declared in the schema. I removed the supplemental_file section and everything loaded normally again. I’m under the impression this only needs to be run and generated once.

Some additional resources

Fabianfnc’s Antora Guide - This website and repository provided me with so much inspiration for this post. It is an amazing foundational guide.

GitHub Pages - The place to start! Their documentation always provides so much great information. If this were a Jekyll-only build, the GitHub Pages site would be the only thing you need.

Antora: Publish to GitHub Pages - This page has more information about the Jekyll and Antora file structure.