Antora Publishing

Julian Elve

Sep 3, 2020 notes

Approaches for publishing Antora projects to websites on Netlify and Azure

Background

As noted in Antora basics the Antora build pipeline generates a static website bundle in ./build/site.

Although it is possible to manually upload the contents of that directory to any webserver, in a real project we want to have automated publishing triggered by pushing changes to either the playbook project or any of the content root repositories.

Publishing destinations

In our real world project we set up a total of three websites - one for our customers, and two restricted sites for internal staff documentation.

The public site is hosted on Netlify, and the two internal sites hosted on Azure App Service with authentication switched on - to visit those sites you have to authenticate with our Azure Active Directory.

Continuous deployment

All of our sites are published automatically whenever changes to either the playbook project or any of the relevant content root repositories are pushed to GitHub.

Change	Site type	Hosting	Build engine	Trigger
Playbook project	Public	Netlify	Netlify	Automatic build triggered by GitHub push
Playbook project	Restricted	Azure	Azure DevOps	Automatic build triggered by GitHub push
Content roots	Public	Netlify	Netlify	GitHub action fires build of associated playbook project via netlify webhook
Content roots	Restricted	Azure	Azure Devops	GitHub action fires build of associated playbook project via Azure DevOps API

Netlify

Ensure playbook project is connected to Netlify
In playbook project add build-site.sh (includes addition of search):
In playbook project add netlify.toml:
Log in to Netlify, create a webhook for the playbook project
In GitHub create an account-level or organisation-level secret called NETLIFY_HOOK_DOCS_PUBLIC with the value set to the URL of the webhook created in step 1
In GitHub add the secret to each content project that contains public docs
In each content project create a GitHub action in ./.github/workflows/build-public.yml that looks like this (we assume content root is always under ./public, edit to suit your setup):

Azure App Service / Azure Devops

Create a connection in Azure Devops to the relevant Azure subscription
In the playbook project add ./azure-pipelines.yml as per the gist below (edit values for Azure subscription and website)
Connect the playbook project to Azure Devops and configure a pipeline based on the ./azure-pipelines.yml file
Login to Azure Devops and create a Personal Access Token
In GitHub create an account-level or organisation-level secret called AZURE_DEVOPS_TOKEN with the value set to the token created in the previous step
In GitHub add the secret to each content project that contains docs used in this project
In each content project add a GitHub action in ./.github/workflows/build-azure.yml that looks like the gist below (the version shown assumes content in the ./staff folder, edit to suit your setup )