Description

Various tools and helpers to build documentation site

Structure

Folder	Description
antora-extensions	extensions for antora site builder
antora-macro	macro for antora site builder
scripts	various scripts for file processing
bin	executables

Installation

Right now we only support direct npm package installation from GitHub, e.g.

 npm i -D hazelcast/hazelcast-docs-tools#v0.0.1-alpha

The part after # is the version of the package, e.g. #v0.0.1-alpha.

Usage

Extensions and Macro

All files inside antora-extensions and antora-macro folders can be used as antora extensions, e.g. in the antora-playbook.yaml file.

  extensions:
    - ./node_modules/hazelcast-docs-tools/antora-macro/tabs-block.js
    - ./node_modules/hazelcast-docs-tools/antora-extensions/api-json.js

Scripts

Scripts can be used by requiring them as Node modules. E.g.

require('hazelcast-docs-tools/scripts/orphan-pages-checker');

Executables

Executables are installed inside the node_modules/.bin, so they can be called directly e.g. in npm scripts:

"check-orphan-pages": "check-orphan-pages",

Tools

File	Type	Description
load-check-links-playbook.js	executable/script	Creates a special Antora Playbook from the global antora-playbook.yml suitable for running the docs validation
orphan-pages-checker.js	executable/script	Checks the whether the current docs pages folders contain the pages which are not mentioned in the navigation.
tabs-block.js	macros	Extends the AsciiDoc syntax to support a tabset
swagger-ui-block-macro.js	macros	Adds support for swagger_ui::{LINK_TO_SWAGGER_YAML}
api-json.js	extension	Adds possibility to get docs or other data as JSON response via HTTP requests
antora-link-checker-extension.js	extension	Stops Antora builder earlier to save time for validation run

Orphan Checker

The check-orphan-pages command takes the following arguments

Name	Description	Default Value
--directory, -d	set the root folder of documentation, if there are several root directories, can take a coma separated list, e.g. -d docs,tutorials	"docs"
--log-failure-level	if set to "error" exits process with 1 if orphan pages are detected	undefined

Check Links Playbook Loader

The load-check-links-playbook command takes the following arguments

Name	Description	Default Value
--repo, -r	repository name
--branch, -b	branch name
--log-level	log level: 'log' or 'debug'	'log'

Release Process

The release process is powered by npm CLI.

1. Switch to the main branch, pull the latest changes.
2. Run in the console npm version [patch|minor|major]. Note the version output in the console after you run the latter command - it will be the new version.
3. Run git push --follow-tags.
4. Go to releases and create a new release with the latest tag (appeared after step 2). Don't forget to check "Set as the latest release".

To use that release clients need to reinstall the package with the new version, e.g. for the version v1.2.3 run npm i -D hazelcast/hazelcast-docs-tools#v1.2.3