As with Hugo, it is possible to configure an Antora project to be built on Netlify. This means that Netlify monitors a designated Git repository (on a provider such as GitHub or GitLab) for changes to a specified build (for example, main) and automatically runs a build whenever changes are detected.

In the case of an Antora project:

  1. You push the site contents (AsciiDoc source) to a repo on your Git provider (in my case on GitHub).

  2. You create a separate playbook project and push that to your Git provider.

  3. In Netlify, you create a link to the playbook repo and specify some build parameters, including the branch that Netlify monitors for changes.

  4. You then initiate the deployment of the site.

    In the process of deploying, Netlify fires up a build environment for Antora plus any dependencies, generates the site, and then destroys the build environment. All of this takes seconds, but it does mean that a deployment consumes some of your allocation of Netlify build minutes. I’ve found that the 300 minutes allocated to the free starter tier is ample.

To try this out, you can use the standard Antora demo doc site. This is a small project that is stored in two repos on GitLab:

The setup is well explained in Install and Run Antora Quickstart.

If you are starting from scratch, you should perform the following steps in the quickstart procedure:

  1. Install Node.js

  2. Install Antora

    This details how to install Antora within the playbook project, which is the preferred approach (as opposed to installing it globally).

  3. Create a playbook

    The playbook specifies, among other things, what content to include, where it is located, and what UI bundle (template) is applied.

Note that at this stage you will have a local copy of the playbook project. You do not have local copies of the two demo components. These are stored on GitLab.

You should now have a doc-site folder with the following contents:

node_modules/
antora-playbook.yml
package.json
package-lock.json

Netlify uses the package.json and package-lock.json files.

The package.json file specifies any dependencies required to run the build. Minimally this is the version of Antora:

package.json
{
  "dependencies": {
  "antora": "~> 3.0"
  }
}

During the installation you ran npm i, which generated the package-lock.json. You can choose to rerun this command in a terminal.

To prepare the project for Netlify, do the following (kindly provided by Dan Allen):

  1. In a text editor, create a netlify.toml file with the following contents:

    [build]
publish = "build/site"
command = "npx antora --redirect-facility=netlify antora-playbook.yml"

    This specifies the command that Netlify will run, as well as the folder in which the site will be published. It is possible to configure these manually in Netlify but this is not recommended.

  2. Create a Git repository in your docs-site folder.

  3. Add the node_modules folder to .gitignore. You don’t want to include the contents in your repo.

  4. Commit and push the docs-site repo to your remote Git. This is typically on GitHub, GitLab, or Bitbucket.

  5. In your Netlify account, click Add new site › Import an existing project.

  6. When prompted to connect to your Git provider, choose GitHub, GitLab, or Bitbucket as appropriate.

  7. Search for the docs-site repo and select it.

    You should see that the build command and publish directory fields have been filled from the netlify.toml file.

  8. Click Deploy site.

    After a few seconds you should see that your site has been deployed.

  9. Follow the automatically generated link to check that the site has deployed correctly.

Note
 Changes to the playbook project (docs-site) will trigger the redeployment of the site. Changes to the content repos (in this case https://gitlab.com/antora/demo/demo-component-a and https://gitlab.com/antora/demo/demo-component-a) will not. This is likely not to be desirable. In next two posts, I consider how to configure scheduled builds and also how to configure builds that occur when the content repos are merged.