README.adoc

= New Bonita Documentation Site
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
// External URIs:
:url-antora: https://antora.org
:url-asciidoctor: https://asciidoctor.org/
:url-node: https://nodejs.org
:url-nvm: https://github.com/creationix/nvm
:url-nvm-install: {url-nvm}#installation


*_DISCLAIMER: this is a work in progress._*


== Architecture

Static site generation based on {url-antora}[Antora] using {url-asciidoctor}:[Asciidoctor] documentation content stored in various Git repositories.


== Build

=== Requirements


{url-node}[Node 12.x] (may work with newer versions, no guarantee). For more details, see the  https://docs.antora.org/antora/2.3/install-and-run-quickstart/[Antora installation guide].

While you can install Node from the official packages, we strongly recommend that you use {url-nvm}[nvm] (Node Version Manager) to install and manage Node.
Follow the {url-nvm-install}[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
```bash
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

[WARNING]
====
The following command https://docs.antora.org/antora/2.3/playbook/runtime-fetch/[fetch the documentation content repositories] each time they are run. +
<<local-content>> or <<preview>> can prevent this to happen.
====


For a site that can be load from local disk
```bash
npm run local:build-static
```

For a site to be served by the development <<http server>>
```bash
npm run local:build
```

[[local-content]]
===== Using local documentation content repositories

This activates the https://docs.antora.org/antora/2.3/playbook/author-mode/[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
  |
  -- bonita-documentation-site
```
====

For more information about the `build-preview.bash` script, see later in this document
```bash
./build-preview.bash --ci false  --type local --local-sources true
```

[[local-ui-bundle]]
===== Using local UI Bundle

The prebuilt UI Bundle is stored in this repository and sources are located in the https://github.com/bonitasoft/bonita-documentation-theme[bonita-documentation theme]
repository. +
If you are developing in the theme repository and want to see the resulting changes in the documentation. It provides a
fast feedback loop as you don't need to push nor commit content as the current work.


Remember that the theme repository provides a preview with mock content that make development easier. But sometimes, integration
tests are required to ensure everything is ok, especially when dealing with https://docs.antora.org/antora/2.3/playbook/site-keys/[site keys].

[NOTE]
.Repositories location
====
This requires to clone the theme repository locally is the parent folder of this project.
For instance
```
root
  |
  -- bonita-documentation-theme
  |
  -- bonita-documentation-site
```
====

For more information about the `build-preview.bash` script, see later in this document
```bash
./build-preview.bash --ci false  --type local --local-ui-bundle true
```

[[preview]]
==== Building for preview

It is possible to use a script that let's generate the documentation partially or with specific settings for both local
developments or Pull Request previews.

This includes building the documentation using:

- already checkout local documentation content repositories
- single branch for all components
- single branch of a single component
- ....

To know all available options, run
```bash
./build-preview.bash --help
```

==== 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 xref:./docs/README[dedicated folder].