Antora is a static site generator that facilitates a docs-as-code workflow.
In Antora, documentation is stored in Git repositories and processed to output a static website.
Documentation can be stored in one or more repositories, using either branches or tags to version it.
Antora uses Asciidoctor.js to convert Asciidoc to HTML, then it uses Handlebars to set that HTML into a page layout.
Note
|
The page layouts and UI code (css, JavaScript, Handlebars templates) are stored in a separate repository, which outputs a ui-bundle.zip file that this project references in the playbook.
|
Tip
|
Learn more about Antora with this excellent introduction on YouTube. |
The playbook defines the content sources (repositories and branches), site URL, UI bundle URL, global AsciiDoc attributes, and Asciidoctor extensions.
This project has two playbook files, which configure the build process for the documentation site:
-
antora-playbook-local.yml
: For local builds -
antora-playbook.yml
: For production builds (used by our hosting provider Netlify)
Source content for the documentation site is marked up in Asciidoc.
The current playbooks pull content from the following repositories:
Inside these repositories, content may be stored in the following:
-
master/main
branch: Thelatest-dev
content, which represents the current development version of the product -
archived-versions
branch: Legacy content that is not hosted on Antora, but instead given a single page with a link to the legacy documentation site -
Branches prefixed with
v/
: Versioned releases
Note
|
To learn about release workflows, see the README of a content repository. |
The home/
folder in this repository contains the Home documentation component. The source code for the home page is in the body-home.hbs
template of the hazelcast-docs-ui
repository.
The custom extension in the lib/
directory processes the Asciidoc tabs
blocks to generate tabbed code samples in the output HTML.
For more information about writing Asciidoctor.js extensions, see the Asciidoctor docs.
The documentation site is hosted on Netlify, which builds two versions of the site from this GitHub repository:
-
Production site: This site is hosted on https://docs.hazelcast.com and is built from the
main
branch -
Staging site: This site is hosted on {url-staging} and is built from the
develop
branch
To preview changes, all pull requests are made to the develop
branch. When the team are happy with the changes, the develop
branch is merged into the main
branch to deploy the changes to the production site.
To make it easy for users to find and bookmark the latest IMDG and Management Center content, we use the following aliases:
-
latest
: The latest stable version -
latest-dev
: The latest development version
These aliases are configured in the _redirects
file, which Netlify uses to redirect to their actual versioned content.
For details about this file, see the Netlify documentation.
The search bar in the documentation is powered by an Algolia search index.
Once a day, we use a DocSearch scraper to index the site, using a GitHub Action, and to send that index to Algolia.
To index the documentation, DocSearch uses our search-config.json
file. For more information about search configuration, see the DocSearch documentation.
To automate some elements of the build process, this repository includes the following GitHub Actions:
File | Description | Triggers |
---|---|---|
|
Runs the DocSearch scraper in a Docker container to index the site and send the index to Algolia |
Once per day at 00:00 UTC |
|
Merges the |
Manual |
As well as these actions, content repositories that are listed under the content.sources
field in the antora-playbook.yml
file also include GitHub actions to trigger builds of the production site.
content:
sources:
- url: https://github.com/hazelcast/imdg-docs
branches: [master]
start_path: docs
Whenever content in the repository’s listed branches are changed, the GitHub Action sends a build hook to Netlify to trigger a new build of the staging site.
For an example of these GitHub Actions, see the IMDG documentation repository.
To learn how to use the playbook and generate the docs site locally, see our contributing guide.