Getting Started With AsciiDoc Using Antora

A popular Static Site Generator (SSG) that supports the use of AsciiDoc syntax is Antora. Static Site Generators are tools that generate a full static HTML website based on raw data and a set of templates and Antora is one that has been designed specifically around the needs of technical writers and their goal; which is to create technical documentation.

Antora is developed around the AsciiDoc syntax or format that is somewhat similar to the Markdown syntax. It also runs on Asciidoctor, a processor that parses and converts AsciiDoc source documents into various formats such as HTML5, PDF, DocBook etc. It provides technical writers with a structured and defined way of organizing technical content.

It is important to note that the developers of Asciidoctor are also the maintainers of Antora, this gives room for proper integration between the two technologies.

To use Antora to generate a document, you need to assemble your files into a standard project structure, and then store them in a git repository. Once that is done, Antora picks your file and transforms it into a website.

Now you will take a look at how to Install Antora.

Installation, Setup and Configuration#

Before installing Antora locally on your computer, it is important to take a look at the Supported Platforms and System Requirements. This is to ensure your development device is supported by the system.

Installing Node.js and Chocolatey for Windows#

After checking for system requirements, you need to ensure you have Node.js installed on your computer. To check if you do, open the PowerShell and type:

1node --version

You should see something like the image below ;

Fig 1. An Image of the PowerShell showing the node version installed

Pin 1 shows the command used to check if Node.js is installed.

Pin 2 shows the version of Node.js installed.

If you are presented with an error in your PowerShell after running the command, that would mean you do not have Node.js installed.

The best way to install to install Node.js is by Chocolatey, a package manager for Windows. Open the PowerShell and run as an Administrator by right-clicking the PowerShell icon and selecting Run as Administrator.

Then run the following command;

1Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.webClient).DownloadString('https://chocolatey.org/install.ps1'))

Fig 2: A screenshot of the PowerShell showing the installation of Chocolatey

Once the command is complete, you can now install node.js

You can install Node.js with Chocolatey by running the following command in the PowerShell;

1choco install nodejs.install

Fig 3: A screenshot of the PowerShell showing the installation of Node.js

Installing Antora#

In this section, you will look at how to install Antora.

Prerequisite: You must have Node.js installed

To be able to use Antora to generate a documentation site, you are going to need the Antora command line interface (CLI) and the Antora site generator.

The first thing to do when trying to install Antora is to create a new directory for your documentation site, and then move into that directory. You can do this in your PowerShell. Let us call this directory test-site

1mkdir test-site
2cd test-site

The next step is to initialize the package.json file and install the necessary CLI package in the project so you can run Antora using Node Package Execute ( npx: a npm package runner that executes any package from the npm registry without having to install it ).

1node -e "fs.writeFileSync('package.json', '{}')"
2npm i -D -E antora

Warning: In case you run into an error running the Antora installation script in the PowerShell of your Windows machine, refer to this article on Execution Policies to fix the issue.

Verify Antora has been installed by running the command below;

1npx antora -v

If the installation is successful, the version of Antora CLI and the site generator specified will be printed onto the PowerShell.

Fig 4: A screenshot of the PowerShell that shows the various processes discussed above

From the Screenshot above, you can see the visual representation of the installation process of Antora in the PowerShell. The processes are pinned and explained below:

Pin 1: creation of the test-site directory

Pin 2: moving into the directory

Pin 3: Initializing the package.json file and other packages

Pin 4: Installing Antora

Pin 5: Verifying Antora, the version installed and the site generator

Creating a Playbook with IDE (Visual Studio Code)#

To create a documentation site, Antora needs a playbook. you will look at how to do that in this section. Follow the following steps

Step 1: Using your preferred IDE, create a new file

Step 2: Add the following configuration information to the file and save it as antora-playbook.yml:

 1site:
 2  title: Antora Docs
 3  start_page: component-b::index.adoc
 4content:
 5  sources:
 6  - url: https://gitlab.com/antora/demo/demo-component-a.git
 7    branches: HEAD
 8  - url: https://gitlab.com/antora/demo/demo-component-b.git
 9    branches: [v2.0, v1.0]
10    start_path: docs
11ui:
12  bundle:
13    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
14    snapshot: true

Fig 5: A screenshot of an IDE showing the antora-playbook.yml file

This configuration file will create a site using the Antora demo repositories.

Step 3: In the terminal, navigate to the test-site directory

Step 4: Run the following command :

1npx antora --fetch antora-playbook.yml

This command lets Antora clone the content, UI repository and generate your documentation site to the default output directory.

Fig 6: A screenshot from the terminal showing that the generation of the documentation site is complete

Navigate to the test-site/build/site/index.html directory. Open the index.html file in your browser to view your generated documentation site.

Fig 7: A screenshot of the generated Antora documentation site.

Congratulations, you just created your first documentation site with Antora.

Testing your Documentation Site and Publishing with Antora#

To be able to publish and test your documentation site, you should do the following:

• In your already created folder, clone the content of this Github repository into it.
• Once you have the repo cloned, now you can work locally on your pc.
• Change into the antora directory and then initialize the json package and install antora by running the following commands;

1node -e "fs.writeFileSync('package.json', '{}')"
2npm i -D -E antora

• Now generate your site by running the following command;

1npx antora antora-playbook.yml

• Now your site should be generated and ready to be viewed. Copy the displayed URL, and paste it into your browser to view your generated site.

• To test for AsciiDoc syntax, navigate to the displayed folder below;

  • antora/
    • docs/
      • modules/
        • module_one/
          • pages/
            • gettingstarted.adoc
            • installation.adoc
            • overview.adoc

• In the gettingstarted.adoc, installation.adoc and overview.adoc files, copy and paste your AsciiDoc syntax into any of the files, then generate the site again by running the “npx antora antora-playboook.yml” command again.

• Go to your browser, and refresh to see your AsciiDoc syntax displayed.

NOTE: For any change you make with syntax in your vs code, always generate the site again by running the “npx antora antora-playbook.yml” command.

• Create a GitHub repository of your own, and push changes you have made to this repo you created.
• Once you have pushed to Github, configure the Github pages for your repo, and set Build and Deployment source to Github Actions.
• Use the Git Action workflow below to deploy your Antora page to GitHub pages.

Be sure to have enabled Github pages in your repo by creating a gh-pages branch

Simple workflow to deploy static content to Github Pages

 1name: Deploy Antora static content to Pages
 2on:
 3  # Runs on pushes targeting the default branch
 4  push:
 5    branches: ["main"]
 6
 7
 8  # Allows you to run this workflow manually from the Actions tab
 9  workflow_dispatch:
10
11
12# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13permissions:
14  contents: write
15  pages: write
16  id-token: write
17
18
19# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
20# However, do NOT cancel in-progress runs as you want to allow these production deployments to complete.
21concurrency:
22  group: "pages"
23  cancel-in-progress: false
24
25
26jobs:
27  deploy:
28    environment:
29      name: github-pages
30      url: ${{ steps.deployment.outputs.page_url }}
31    runs-on: ubuntu-latest
32
33
34    steps:
35      - name: Checkout
36        uses: actions/checkout@v4
37
38
39      - name: Setup Pages
40        uses: actions/configure-pages@v4
41
42
43      - name: Upload artifact
44        uses: actions/upload-pages-artifact@v3
45        with:
46          # Upload entire repository
47          path: "./build/site"
48
49
50      - name: Deploy to GitHub Pages
51        id: deployment
52        uses: actions/deploy-pages@v4
53        with:
54          github_token: ${{ secrets.GITHUB_TOKEN }}
55          publish_dir: ./build/site # Update this to match your Antora output directory

• Make edits to your documentation file.
• Commit changes and push them to your repository.
• Your content will be live once changes have been to the repository.