passga / bonitasoft.github.io

The new solution under development for the Bonita Documentation

New Bonita Documentation Site

DISCLAIMER: this is a work in progress.

Architecture

Static site generation based on Antora using Asciidoctor documentation content stored in various Git repositories.

Build

Requirements

Node 12.x (may work with newer versions, no guarantee). For more details, see the Antora installation guide.

While you can install Node from the official packages, we strongly recommend that you use nvm (Node Version Manager) to install and manage Node. Follow the nvm installation instructions to set up nvm on your machine.

Note	all npm commands are intended to be run from the repository root folder.

Build the static site for production

Run

npm install
npm run build

The static site is then available in the build/site folder.

Local development

The antora CLI is available by calling ./node_modules/.bin/antora --version

For more CLI options, see https://docs.antora.org/antora/2.3/cli/options/

Building for local developments

For a site that can be load from local disk

npm run local:build-static

For a site to be served by the development http server

npm run local:build

Using local documentation content repository

This activates the Antora author mode. The local content of the repository is used instead of fetching the remote one.

It provides a fast feedback loop as you don’t need to push nor commit content as the current work

Note	Repositories location This requires to clone all repository sources locally is the parent folder of this project. For instance root | -- bonita-doc | -- bonita-ici-doc | -- bonitasoft.github.io

npm run local:build-static:local-content

http server

Once the static site is build, you can run npm run serve and access to http://localhost:8080/ to check if everything is working correctly (urls in taxononmy, links, …​.).

You can rebuild the site while the server is running, updated files are directly considered by the server (no cache).

Documentation

See the dedicated folder.