Hazelcast Guides Site

The site root of Hazelcast Guides containing the Antora-generated files hosted by GitHub Pages.

Repository Structure

• docs/: Contains the files generated by Antora. GitHub Pages site is built from this folder in the master branch.
• home/: Contains the home page component where all guides are listed.
• lib/: Contains custom Asciidoc extensions.
• create.sh: Script to create the pages from scratch by pulling the latest commits of all guide repositories.

Contributing

To add a new guide:

1) Create Repository

Create a new repository using the template Base Guide. Use a brief name for the new repository as it will be the endpoint of the guide when it's published.

2) Customize the Template

The template base guide will serve all the required files and scripts. Following the comments in each of them, update:

• doc/antora.yml
• doc/modules/ROOT/pages/index.adoc
• README.md

3) Preview the Changes

See Preview section below.

4) Add Repository Secret

In order publisher GitHub action to work, SECRET_TOKEN must be added as a repository secret. This action will take care of publishing the changes made on your repo.

5) Create Pull Request

When you are done with your guide, create a PR to this repo which updates antora-playbook.yml and the home page (See Preview section for the details.). After it's merged, the guide will be published on the website.

Preview

You can preview the changes before publishing a new guide or making some changes to the existing ones. Before adding a new guide, make sure the repository has the same file hierarchy as Base Guide.

1) Update Antora Playbook

If you create a new guide, then add the new repository to antora-playbook.yaml. To see the changes on an existing one, find the corresponding repository in the playbook and update the url and/or the branch name.

- url: https://github.com/changeme/foo.git
  branches: bar
  start_path: doc

2) Update Homepage

If you add a new guide, then update home/modules/ROOT/pages/index.adoc such that the new guide is placed under an appropriate section.

[.guide]
=== image:your-framework-logo.png[] xref:<changeme>:ROOT:index.adoc[New Guide Title]

Learn how to ...

The <changeme> part must be the name you set in doc/antora.yml of the new guide's repository.

name: guide-name
title: Guide Title
version: master

3) Create the Site

$ sh create.sh

Open docs/index.html to preview the changes. Note that, when running locally, some pages are shown in this format:

Name        Size            Date Modified
_images/                    1/19/21, 10:23:02 AM
index.html  15.6 kB         1/19/21, 10:28:32 AM

Navigate to index.htmls and continue previewing. This will not be an issue when hosted on GitHub Pages.

Editing a Published Guide

All guides come with a publisher GitHub action which kicks in when a file under doc/ folder (in guide's repository) is edited. The action runs create.sh of this repository and pushes the latest changes to this repository. Note that this action needs SECRET_TOKEN to be added as a repository secret at guides' repositories.