Part 2: Launching an Antora website with GitHub Pages (A lively tutorial… based on personal experience)
Please visit (https://specterhead.github.io) for the documentation that inspired this post.
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.
To make and publish a user GitHub Pages site, you need to have a repository with the naming convention: <username>.github.io.
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.
/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.
antora-playbook.yml file with the correct file paths to pull from this repository.https://<username>.github.iohttps://github.com/<username>/<username>.github.io)master and start_path is docs3.a. While we’re updating the playbook file, we will also need to update the UI source.
- Follow the UI URL file path from the Antora Docs page. This will download a compressed file
ui-bundle.zipto your computer.- Upload this uncompressed file to your repository, and place just inside the
/docsfolder, as noted above.- 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: .nojekyllSee the section “Some strange problems I encountered along the way” for an update to this addition.
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.
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).
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.
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>
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! Refresh, then wait anywhere between 30 seconds and 20 minutes (GitHub needs time to build the site), and you will have launched an Antora SSG to GitHub Pages at https://.github.io!
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.
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.