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.

Netlify

1. Ensure playbook project is connected to Netlify
2. In playbook project add build-site.sh (includes addition of search):

   DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm -g root)" antora --fetch --generator antora-site-generator-lunr antora-playbook.yml

   view raw build-site.sh hosted with ❤ by GitHub
3. In playbook project add netlify.toml:

   	# Note you must also set the following environment varibables in the Netlify UI:
   	# GITHUB_CREDENTIALS - a credential that can access private source repos linked from this publishing repo
   	# See https://docs.antora.org/antora/2.3/playbook/private-repository-auth/#pass-credentials-via-an-environment-variable
   	# Settings in the [build] context are global and are applied to all contexts
   	# unless otherwise overridden by more specific contexts.
   	[build]
   	# Directory to change to before starting a build.
   	# This is where we will look for package.json/.nvmrc/etc.
   	base = ""
   	# Directory that contains the deploy-ready HTML files and assets generated by
   	# the build. This is relative to the base directory if one has been set, or the
   	# root directory if a base has not been set. This sample publishes the
   	# directory located at the absolute path "root/project/build-output"
   	publish = "build/site"
   	# Default build command.
   	command = "npm i -g @antora/cli @antora/site-generator-default antora-site-generator-lunr && chmod 0755 ./build-site.sh && ./build-site.sh"

   view raw netlify.toml hosted with ❤ by GitHub
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)

   	trigger:
   	- master
   	pool:
   	vmImage: 'ubuntu-latest'
   	variables:
   	- group: Credentials
   	jobs:
   	- job: build
   	steps:
   	- script: |
   	node --version
   	sudo npm i -g @antora/cli@2.3 @antora/site-generator-default@2.3
   	sudo npm i -g antora-site-generator-lunr
   	antora version
   	displayName: 'Install antora'
   	- script: |
   	export GIT_CREDENTIALS='https://$(PAT):@github.com'
   	DOCSEARCH_ENABLED=true DOCSEARCH_ENGINE=lunr NODE_PATH="$(npm-groot)"antora--fetch--to-di{r}^{\prime }$(Build.ArtifactStagingDirectory)' --generator antora-site-generator-lunr antora-playbook.yml
   	displayName: 'Run antora'
   	- publish: '$(Build.ArtifactStagingDirectory)'
   	artifact: 'myartifactname'
   	- job: publishWeb
   	dependsOn: build
   	steps:
   	- checkout: none # no need to checkout any code because we only need the artifact
   	- download: current
   	artifact: 'myartifactname'
   	- task: AzureRmWebAppDeployment@4
   	inputs:
   	ConnectionType: 'AzureRM'
   	azureSubscription: 'MyAzureSubscription'
   	appType: 'webApp'
   	WebAppName: 'mywebsitename'
   	packageForLinux: '$(Pipeline.Workspace)/myartifactname/'

   view raw azure-pipelines.yml hosted with ❤ by GitHub
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 )

   	name: Trigger Azure Build for Staff Docs
   	on:
   	push:
   	branches:
   	- master
   	paths:
   	- 'staff/**'
   	jobs:
   	trigger-build:
   	runs-on: ubuntu-latest
   	steps:
   	- uses: actions/checkout@v2
   	- uses: Azure/pipelines@v1
   	with:
   	azure-devops-project-url: 'https://dev.azure.com/ORGNAME/PROJECTNAME'
   	azure-pipeline-name: 'PIPELINE_NAME'
   	azure-devops-token: '${{ secrets.AZURE_DEVOPS_TOKEN }}'

   view raw build-azure.yml hosted with ❤ by GitHub