kwart/hazelcast-docs

Hazelcast documentation playbook

Hazelcast Documentation Site

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

Work in progress

The roadmap for this site includes the following items:

• ❏ Migrate Hazelcast Cloud content

• ❏ Migrate Jet content

• ✓ Migrate Management Center content

• ❏ Review and restructure content, starting with IMDG

Introduction to Antora

Antora is a static site generator that facilitates a docs-as-code workflow where documentation is stored in Git repositories and processed to output a static website.

Documentation can be stored in one or more repositories and/or branches.

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) is stored in a separate repository, which outputs a ui-bundle.zip file that this project references in the playbook.

The playbook

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

The current playbooks pull from the following content sources:

• The master, archive, and all v branches of the imdg-docs repository and the mc-docs repository

• The home/ folder in this repository, which contains an Antora component for the home page

Home Component

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.

Custom Asciidoctor Extensions

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.

Production and Staging Sites

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://60116f027a05f66bcc0ce5d4—​nifty-wozniak-71a44b.netlify.app/home/index.html 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.

GitHub Actions

To automate some elements of the build process, this repository includes the following GitHub Actions:

Table 1. GitHub Actions

File	Description	Triggers
index-site.yml	Runs the Docsearch indexer in a Docker container to index the site and send the index to Algolia	Once per day at 00:00 UTC

As well as these actions, repositories that are listed under the content.sources field in the antora-playbook.yml file also include GitHub actions to trigger builds of the staging site.

content:
  sources:
  - url: https://github.com/hazelcast/imdg-docs
    branches: [master, v*]
    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.

Contributing

To learn how to use the playbook and generate the docs site locally, see our contributing guide.