This repository hosts an Antora playbook project for the Hazelcast documentation site.

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.

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:

• Hazelcast 5.0 documentation

• Cloud documentation

• IMDG documentation

• Management Center documentation

Inside these repositories, content may be stored in the following:

• master/main branch: The latest-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

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:

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.

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.