= Bonita Documentation Theme :icons: font ifdef::env-github[] :note-caption: :information_source: :tip-caption: :bulb: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning: endif::[]

This project produces the Antora UI bundle used by the https://github.com/bonitasoft/bonita-documentation-site[bonita-documentation-site] repository to build the Bonita documentation website. + It is based on the https://gitlab.com/antora/antora-ui-default[Antora Default UI].

📣 Want to see them in action? Let's have a look at:

• the https://bonitasoft.github.io/bonita-documentation-theme/[theme preview environment]
• the https://documentation.bonitasoft.com/[Bonita documentation production site]

To report a Bug or submit a Feature Request, go to the https://github.com/bonitasoft/bonita-documentation-site/issues/[bonita-documentation-site issues].

== Prerequisites

The project requires Node 16, for nvm user, run nvm use.

For more details, see the https://docs.antora.org/antora-ui-default/prerequisites/[prerequisites].

== Usage

This repository produces a zip archive ui-bundle.zip. This archive is meant to be used by Antora, it is referenced in the main Antora https://github.com/bonitasoft/bonita-documentation-site/blob/master/antora-playbook.yml[configuration file].

== Release process

The process to release a new version of the theme is fully automated with GitHub Actions.

[TIP]

Simple flow to 'release' a new version of the theme (i.e. use a new version of the UI bundle in the doc site):

• Go in the https://github.com/bonitasoft/bonita-documentation-theme/actions/workflows/create-tag.yml[GitHub Actions] section

• Run the workflow

This process will:

• Create a new tag
• Generate the theme bundle (ui-bundle.zip), and rename it with the release version
• Create a new release and attach the theme bundle as a release asset
• Send a Repository Dispatch event to the https://github.com/bonitasoft/bonita-documentation-site[bonita-documentation-site] repository

When this event is received, a new Pull Request is created in the https://github.com/bonitasoft/bonita-documentation-site[bonita-documentation-site] repository, with an updated theme bundle URL.

== Development

A static or live preview of the theme is available, run npm run dev, or npm run devlive to enable the live reload. For more details, see the https://docs.antora.org/antora-ui-default/build-preview-ui/[build-preview-ui] documentation. + ⚠️ Note that the live reload does not always work, so use it with caution. A restart of the browser, or running npx browserslist@latest --update-db when asked may help.

To build the bundle to be used in the Antora playbook, run npm run bundle.

=== Change some colors in the UI

If you are only here to update some colors in the UI, it should be easy. + All used colors are defined in src/stylesheets/globals.var.scss + At the beginning of the file, you will find the light colors and at the bottom of the file the dark colors. + If you need to add a new color in the color set, then you have to:

• Create a variable --color-XXX in the light color set
• Create a variable --color-XXX in the dark color set
• Use this new color by using var(--color-XXX) in some css classes

[CAUTION]

If you simply update an existing color, your change will probably impact different elements of the UI. + Make sure that the whole UI is OK before submitting your change, in both light and dark !

=== Perform some structural changes in the UI

This UI bundle is based on the Antora default UI. It uses gulp, handlebars and sass. + You can find the detailed documentation on the UI bundle https://docs.antora.org/antora-ui-default/[here].

=== Integrating changes from Antora UI Default

You can find the original code in the antora-ui-default branch of this repository or at https://gitlab.com/antora/antora-ui-default[GitLab].

This branch contains all improvements and bug fixes available in the Antora UI Default project that can be reintegrated in bonita-documentation-theme.

==== Updating the antora-ui-default branch

Add the GitLab repository as remote of your local repository

$ git remote add antora-ui-default https://gitlab.com/antora/antora-ui-default.git

Update the antora-ui-default branch to reference the latest commits of the master branch of the Antora Default UI repository

$ git reset --hard antora-ui-default/master

Push the changes to GitHub (assuming that origin is the alias for the GitHub repository)

$ git push origin antora-ui-default