Skip to content

Latest commit

 

History

History
104 lines (66 loc) · 4.49 KB

README.adoc

File metadata and controls

104 lines (66 loc) · 4.49 KB
Raw

Bonita Documentation Theme

This project produces the Antora UI bundle used by the bonita-documentation-site repository to build the Bonita documentation website.
It is based on the Antora Default UI.

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

To report a Bug or submit a Feature Request, go to the bonita-documentation-site issues.

Prerequisites

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

For more details, see the 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 configuration file.

Release process

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

💡

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

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 bonita-documentation-site repository

When this event is received, a new Pull Request is created in the 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 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

🔥

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 here.

Integrating changes from Antora UI Default

You can find the original code in the antora-ui-default branch of this repository or at 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