Antora Publishing #

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.

ChangeSite typeHostingBuild engineTrigger
Playbook projectPublicNetlifyNetlifyAutomatic build triggered by GitHub push
Playbook projectRestrictedAzureAzure DevOpsAutomatic build triggered by GitHub push
Content rootsPublicNetlifyNetlifyGitHub action fires build of associated playbook project via netlify webhook
Content rootsRestrictedAzureAzure DevopsGitHub action fires build of associated playbook project via Azure DevOps API

Netlify

  1. Ensure playbook project is connected to Netlify
  2. In playbook project add build-site.sh (includes addition of search):
  3. In playbook project add netlify.toml:
  4. Log in to Netlify, create a webhook for the playbook project
  5. 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
  6. In GitHub add the secret to each content project that contains public docs
  7. 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

  1. Create a connection in Azure Devops to the relevant Azure subscription
  2. In the playbook project add ./azure-pipelines.yml as per the gist below (edit values for Azure subscription and website)
  3. Connect the playbook project to Azure Devops and configure a pipeline based on the ./azure-pipelines.yml file
  4. Login to Azure Devops and create a Personal Access Token
  5. 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
  6. In GitHub add the secret to each content project that contains docs used in this project
  7. 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 )
Avatar
Julian Elve
Proactive application of technology to business

My interests include technology, personal knowledge management, social change

Related