See the dedicated folder for
-
documentation content contribution tips/guidelines
-
architecture
-
maintainers guides
-
and much more
More details are available in the Architecture Documentation.
Node 16.x (may work with newer versions, no guarantee).
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. Then run nvm use
.
ℹ️
|
|
Don’t forget to run npm install
the first time you build the project or on package.json
changes.
Check that the Antora
CLI is available by calling ./node_modules/.bin/antora --version
.
The easiest way is to use a script that generates the documentation partially and/or with specific settings for both local developments, Pull Request previews or to produce documentation archives.
This includes building the documentation using:
-
already checkout local documentation content repositories
-
single branch for all components
-
single branch of a single component
-
a set of branches of various components. It lets validate references between pages that belong to different docs components and/or versions
-
….
To know all available options, run
./build-preview.bash --help
ℹ️
|
An additional |
./build-preview-dev.bash --local-sources \
--component bonita \
--branch fix/a_major_documentation_content_fix
./build-preview-dev.bash \
--use-multi-repositories \
--component-with-branches bcd:3.4 \
--component-with-branches bonita:7.11,2021.1
The documentation is built by passing a playbook file to the Antora CLI. For more details, see Antora CLI documentation.
For the preview support, we generate a dedicated Antora playbook based on the production playbook store in the repository
and options passed to the build-preview.bash
.
Then, this custom playbook is passed to the Antora CLI along with specific options when needed.
This activates the Antora author mode.
Antora uses the locally cloned repositories as they are on your local machine instead of cloning them from their remote location.
This provides a fast feedback loop as you don’t need to push nor commit sources content. This also makes developments easier when working offline.
ℹ️
|
Repositories location
This requires to clone content sources repositories locally is the parent folder of this project. Depending on which sources you use (see the options of the bash script), you may have to clone all, or a part of the repositories used by the Bonita documentation. For instance: root | -- bonita-cloud-doc | -- bonita-continuous-delivery-doc | -- bonita-doc | -- bonita-documentation-site | -- bonita-labs-doc |
This can be achieved by running
./build-preview-dev.bash --local-sources ....
To play with settings, validate the UI Bundle, experiment AsciiDoc syntax and much more, the bonita-documentation-site
repository provides
a test site structure with documentation content.
The generation site generation is very fast, so using this content reduces the feedback loop.
This can be achieved by running
./build-preview-dev.bash --use-test-sources ....
The prebuilt UI Bundle is stored in this repository and sources are located in the bonita-documentation theme
repository.
If you are developing in the theme repository and want to see the resulting changes in the documentation, you can directly
use the UI Bundle built by the theme repository.
This provides a fast feedback loop as you don’t need to build copy the UI bundle from the theme repository and then run
a build command: everything can be done by running a single command once the 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 site keys.
ℹ️
|
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 |
This can be achieved by running
./build-preview-dev.bash --local-ui-bundle ...
For a faster loop, don’t forget you can build the UI Bundle and the preview by chaining the commands
<ui_bundle_build_command> ; ./build-preview-dev.bash --local-ui-bundle ...
Sometimes, you need to compare the site rendering with this bundle if you suspect a bug in the Bonita documentation theme.
This can be achieved by running
./build-preview-dev.bash --default-ui-bundle ...
If you want to ensure you use the latest version of the bundle pass --default-ui-bundle snapshot
. Otherwise, a cache
version is used. For more details, see the Antora Documentation
If you need/want to experiment changes without rebuilding the theme, especially if the changes only involve the template, you can directly put the files in the documentation site.
See the Antora supplemental UI for a complete explanation.
ℹ️
|
Most of the time, pages can be browsed locally without requiring a http dev server. |
Once the static site is build, you can run npm run serve
and access it with http://localhost:8080
to check if everything is working correctly (urls in taxonomy, links, ….).
You can rebuild the site while the server is running, updated files are directly considered by the server (no cache).
To ensure all links are correctly generated for local deployment, pass the --site-url http://localhost:8080
options
when building the preview.
💡
|
A http server is needed to correctly see the Asciinema resources (loading fail when using a local file browsing). |
💡
|
The http dev server is provided by the Netlify CLI, so it is able to replicate a lot of the Netlify Edge features. See for configure Netlify redirects how-to more details. |
|
This is probably something you won’t often do as the site is not fully working for local browsing nor for simple http server. |
🔥
|
The following command fetch the documentation content repositories each time it runs. |
Run npm run build