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/
directory 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 tutorials/
directory in this repository contains the Tutorials documentation component. The source code for the tutorials subsite is in the tutorials-*.hbs
templates of the hazelcast-docs-ui
repository.
For information about contributing new tutorials, see Tutorial Templates
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 https://develop—nifty-wozniak-71a44b.netlify.app/home/ 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 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.
You can generate a PDF of the following documentation:
-
Hazelcast Platform version 5.0
-
Hazelcast Platform version 5.1
To generate PDFs, you’ll need the following prerequisites:
-
At least Ruby 2.7
-
Node.js 16, preferably using nvm for the install
-
Make sure that the PATH environment variable includes both Ruby and Node
To generate the PDFs, do the following in the root of this repository:
-
Install the dependencies.
npm i
-
Install Asciidoctor PDF.
bundle --path=.bundle/gems
NoteOn Windows, you may need to replace the forward slash in the --path
value with a backslash (i.e.,--path=.bundle\gems
). -
Execute a script to generate the PDFs for a version of the documentation.
npm run-script generate-pdfs-platform-5-1
This script generates a PDF for the Hazelcast Platform 5.1 documentation.
The result of this script is a pdf-docs
directory, in which the artifacts for the PDF files are assembled and the PDF files are generated.
Some errors are displayed in the output, but you can ignore them.
-
Management Center links are broken: Since the script builds only a PDF of the Platform documentation, it’s normal that these links are broken.
-
null startLine
: The script uses the Antora assembler extension, which is in an alpha state. These errors are generated from the PDF converter. The output does not appear to be broken, so you can ignore this type of error.
We will track the status of the extension and update it when new releases are available.
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 |
1st and 15th of every month 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.