README.adoc 3.87 KB
Newer Older
Adrien's avatar
Adrien committed
1
= Bonita Documentation Theme
2
3
4
5
6
7
8
9
:icons: font
ifdef::env-github[]
:note-caption: :information_source:
:tip-caption: :bulb:
:important-caption: :heavy_exclamation_mark:
:caution-caption: :fire:
:warning-caption: :warning:
endif::[]
Macbook Adrien - Bonita's avatar
Macbook Adrien - Bonita committed
10

11
This project produces the Antora UI bundle used by the https://github.com/bonitasoft/bonita-documentation-site[bonita-documentation-site]
12
repository to build the Bonita documentation website. +
13
It is based on the https://gitlab.com/antora/antora-ui-default[Antora Default UI].
Macbook Adrien - Bonita's avatar
Macbook Adrien - Bonita committed
14

15
16
17
18
19
20
21
22

== Prerequisites

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

For more details, see the xref:docs/modules/ROOT/pages/prerequisites.adoc[prerequisites].


Adrien's avatar
Adrien committed
23
== Usage
Macbook Adrien - Bonita's avatar
Macbook Adrien - Bonita committed
24

25
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]. +
26
Currently, we embed the ui-bundle.zip in the main https://github.com/bonitasoft/bonita-documentation-site/tree/master/resources[documentation site repository], it is used locally at build time.
Macbook Adrien - Bonita's avatar
Macbook Adrien - Bonita committed
27

28
29
30
[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):
Macbook Adrien - Bonita's avatar
Macbook Adrien - Bonita committed
31

32
- Build locally this repository (type `gulp bundle` at the root of the repository) -> _build/ui-bundle.zip_ is created +
33
34
- Clone the repository https://github.com/bonitasoft/bonita-documentation-site[bonita-documentation-site], and create a new branch to update the UI bundle
- Copy the ui-bundle.zip archive in _bonita-documentation-site/resources/_, and rename it into _antora-ui-bundle.zip_ +
35
36
37
38
- Push your changes and open a pull request, with details on the changes and eventually some links to the change commits in this repository
====

== Development
39
40
41
42
43

A static or live preview of the theme is available, see the xref:docs/modules/ROOT/pages/build-preview-ui.adoc[build-preview-ui]
documentation.

To build the bundle to be used in the Antora playbook, run `gulp bundle`.
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66

=== 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/stylsheets/globals.var.scss_ +
At the beggining of the file, you will find the light colors and  the dark colors. +
If you need to add a new color in the color set, then you have to:

- Create a variable `--color-XXX-light` in the light color set
- Create a variable `--color-XXX-dark` in the dark color set
- Add `'--color-XXX'` in the color list at the beggining of the file _src/js/header-01-theme.js_
- 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].
67
68
69
70
71
72
73
74
75
76
77


=== 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
78
79

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

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

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

85
Push the changes to GitHub (assuming that `origin` is the alias for the GitHub repository)
86
87

  $ git push origin antora-ui-default