docs: update documentation

docs/assets/scss/_alerts.scss

@@ -0,0 +1,5 @@
+.alert-info {
+    border-style: solid;
+    border-color: #33c5c5;
+    border-width: 0 0 0 4px;
+}

docs/assets/scss/_styles_project.scss

@@ -66,9 +66,42 @@ main {
     color: $secondary!important;
 }
 
+h2 {
+    font-weight: 800;
+    color: #223232;
+}
+
+h3 {
+    font-weight: 800;
+    color: #223232;
+}
+
 h3 > code {
     color:$primary !important;
     word-break: normal;
     background-color: rgba(0, 0, 0, 0.05);
     border-radius: 0.25rem;
+}
+
+.pageinfo-info {
+    border-style: solid;
+    border-color: #33c5c5;
+}
+
+.alert-heading {
+    font-weight: bold;
+}
+
+.alert-info {
+    border-style: solid;
+    border-color: #33c5c5;
+    border-width: 0 0 0 4px;
+
+    h4.alert-heading {
+        color: #33c5c5;
+    }
+}
+
+.alert-warning {
+    border-width: 0 0 0 4px;
 }

docs/content/en/docs/Concepts/reconciliation.md

@@ -1,41 +1,42 @@
 ---
+tags: [ "concept" ]
 title: "Reconciliation"
 linkTitle: "Reconciliation"
 weight: 3
 ---
 
 {{% pageinfo color="info" %}}
-In the context of Jikkou, reconciliation refers to the process by which the current state of a desired object
-is compared to the actual state of the system and any differences (called _changes_) between the two are reconciled or
-corrected.
+In the context of Jikkou, reconciliation refers to the process of comparing the desired state of an object with the
+actual state of the system and making any necessary corrections or adjustments to align them.
 {{% /pageinfo %}}
 
 ### Changes
 
 A _Change_ represents a difference, detected during reconciliation, between two objects that can reconciled or
 corrected by adding, updating, or deleting an object or property attached to the actual state of the system.
 
-Jikkou computes four types of changes:
+A _Change_ represents a detected difference between two objects during the reconciliation process. These differences can
+be reconciled or corrected by adding, updating, or deleting an object or property associated with the actual state of
+the system
 
-* **ADD**: Indicates that a new object or a property of an existing object was added.
-* **UPDATE**: Indicates that an existing object or a property of an existing object was changed.
-* **DELETE**: Indicates that an existing object must be deleted or a property of an existing object was removed.
-* **NONE**: Indicates that an existing object or property was not changed.
+* Jikkou identifies four types of changes:
 
-### Reconciliation Modes
+* **ADD**: Indicates the addition of a new object or property to an existing object.
+* **UPDATE**: Indicates modifications made to an existing object or property of an existing object.
+* **DELETE**: Indicates the removal of an existing object or property of an existing object.
+* **NONE**: Indicates that no changes were made to an existing object or property.
 
-Depending on the chosen reconciliation mode, only specific types of changes may be applied.
+### Reconciliation Modes
 
-Jikkou defines the following four distinct reconciliation modes:
+Depending on the chosen reconciliation mode, only specific types of changes will be applied.
 
-Jikkou offers four distinct reconciliation modes that determine which types of changes will be applied:
+Jikkou provides four distinct reconciliation modes that determine the types of changes to be applied:
 
-* **CREATE**: Only changes that create new resource objects on your system will be applied.
-* **DELETE**: Only changes that delete existing resource objects on your system will be applied.
-* **UPDATE**: Only changes that create or update existing resource objects on your system will be applied.
-* **APPLY_ALL**: Apply all changes to ensure that the actual state of a resource in the cluster matches the desired
-  state as defined in your resource definition file, regardless of the specific type of change.
+* **`CREATE`**: This mode only applies changes that create new resource objects in your system.
+* **`DELETE`**: This mode only applies changes that delete existing resource objects in your system.
+* **`UPDATE`**: This mode only applies changes that create or update existing resource objects in your system.
+* **`APPLY_ALL`**: This mode applies all changes to ensure that the actual state of a resource in the cluster matches
+  the desired state defined in your resource definition file, regardless of the specific type of change.
 
-{{% alert title="Note" color="info" %}}
-The reconciliation modes listed above correspond to the _commands_ available through the Jikkou CLI.
-{{% /alert %}}
+Each mode corresponds to a command offered by the Jikkou CLI (i.e., `create`, `update`, `delete`, and `apply`). Choose
+the appropriate mode based on your requirements.

docs/content/en/docs/Concepts/resource.md

@@ -1,4 +1,5 @@
 ---
+tags: [ "concept" ]
 title: "Resource"
 linkTitle: "Resource"
 weight: 1

docs/content/en/docs/Concepts/selectors.md

@@ -1,4 +1,5 @@
 ---
+tags: [ "concept", "feature" ]
 title: "Selectors"
 linkTitle: "Selectors"
 weight: 4

docs/content/en/docs/Concepts/template.md

@@ -0,0 +1,205 @@
+---
+tags: [ "concept", "feature" ]
+title: "Template"
+linkTitle: "Template"
+weight: 7
+description: >
+  Learn how to use templating to dynamically build resource definition files.
+---
+
+{{% pageinfo color="info" %}}
+_Template_ helps you to dynamically define _resource definition files_  from external data.
+{{% /pageinfo %}}
+
+## Template Engine
+
+Jikkou provides a simple templating mechanism based-on [Jinjava](https://github.com/HubSpot/jinjava), a Jinja template
+engine for Java.
+
+Read the official documentation of [Jinja](https://jinja.palletsprojects.com/en/3.1.x/templates/#base-template) to learn
+more about the syntax and semantics of the template engine.
+
+## How Does It Work ?
+
+Jikkou performs the rendering of your template in two phases:
+
+1. First, an initial rendering is performed using only the `values` and `labels` passed through the command-lines
+   arguments.
+    * Thus, it is perfectly OK if your resource file is not initially a valid YAML file.
+2. Then, a second and final rendering is performed after parsing the YAML resource file using the additional `values`
+   and `labels` as defined into the YAML resource file.
+    * Therefore, it's important that your resource file is converted into a valid YAML file after the first rendering.
+
+{{< figure src="jikkou-template-how-it-work.png" width="50%" class="center" >}}
+
+{{% alert title="Important" color="warning" %}}
+You should use `{% raw %}...{% endraw %}` tags to ensure the variables defined into the `template` are not be
+interpreted during the first rendering.
+{{% /alert %}}
+
+## Variables
+
+Jikkou defines a number of top-level variables that are passed to the template engine.
+
+* `values`:
+    * The values passed into the template through the command-line  `--values-files` and/or `--set-value` arguments
+    * In addition, values can be defined into the `application.conf` file and directly into the template file using the
+      property `template.values`.
+    * By default, `values` is empty.
+
+
+* `labels`:
+    * The labels passed into the template through the command-line argument: `--set-label`.
+    * In addition, labels can be defined into the template file using the property `metadata.labels`.
+    * By default, `labels` is empty.
+
+
+* `system.env`:
+    * This provides access to all environment variables.
+
+
+* `system.props`:
+    * This provides access to all system properties.
+
+## Template Values
+
+When using templating, a _resource definition file_ may contain the additional property `template`.
+fields:
+
+```yaml
+apiVersion: The api version (required)
+kind: The resource kind (required)
+metadata:
+  labels: The set of key/value pairs that you can use to describe your resource file (optional)
+  annotations: The set of key/value pairs automatically generated by the tool (optional)
+template:
+  values: The set of key/value pairs to be passed to the template engine (optional)
+spec: Specification of the resource
+```
+
+## Values Data File
+
+**Values Data File** are used to define all the necessary values (i.e., the variables) to be used for generating a template.
+
+### Example
+
+```yaml
+# file: ./values.yaml
+topicConfigs:
+  partitions: 4
+  replicas: 3
+topicPrefix: "{{ system.env.TOPIC_PREFIX | default('test', true) }}"
+countryCodes:
+  - fr
+  - be
+  - de
+  - es
+  - uk
+  - us
+```
+
+## Template Resource File
+
+### Example
+
+```yaml
+# file: ./kafka-topics.tpl
+apiVersion: 'kafka.jikkou.io/v1beta2'
+kind: 'KafkaTopicList'
+items:
+  { % for country in values.countryCodes % }
+  - metadata:
+      name: "{{ values.topicPrefix}}-iot-events-{{ country }}"
+    spec:
+      partitions: { { values.topicConfigs.partitions } }
+      replicas: { { values.topicConfigs.replicas } }
+      configMapRefs:
+        - TopicConfig
+    { % endfor % }
+---
+apiVersion: "core.jikkou.io/v1beta2"
+kind: "ConfigMap"
+metadata:
+  name: TopicConfig
+template:
+  values:
+    default_min_insync_replicas: "{{ values.topicConfigs.replicas | default(3, true) | int | add(-1) }}"
+data:
+  retention.ms: 3600000
+  max.message.bytes: 20971520
+  min.insync.replicas: '{% raw %}{{ values.default_min_insync_replicas }}{% endraw %}'
+```
+
+**Command**
+
+```bash
+$  TOPIC_PREFIX=local jikkou validate --files topics.tpl --values-files values.yaml 
+```
+
+**(Output)**
+
+```yaml
+---
+apiVersion: "kafka.jikkou.io/v1beta2"
+kind: "KafkaTopicList"
+metadata:
+  labels: { }
+  annotations:
+    jikkou.io/resource-location: "file:///tmp/jikkou/topics.tpl"
+spec:
+  topics:
+    - metadata:
+        name: "local-iot-events-fr"
+      spec:
+        partitions: 4
+        replicas: 3
+        configs:
+          min.insync.replicas: "2"
+          retention.ms: 3600000
+          max.message.bytes: 20971520
+    - metadata:
+        name: "local-iot-events-be"
+      spec:
+        partitions: 4
+        replicas: 3
+        configs:
+          min.insync.replicas: "2"
+          retention.ms: 3600000
+          max.message.bytes: 20971520
+    - metadata:
+        name: "local-iot-events-de"
+      spec:
+        partitions: 4
+        replicas: 3
+        configs:
+          min.insync.replicas: "2"
+          max.message.bytes: 20971520
+          retention.ms: 3600000
+    - metadata:
+        name: "local-iot-events-es"
+      spec:
+        partitions: 4
+        replicas: 3
+        configs:
+          min.insync.replicas: "2"
+          max.message.bytes: 20971520
+          retention.ms: 3600000
+    - metadata:
+        name: "local-iot-events-uk"
+      spec:
+        partitions: 4
+        replicas: 3
+        configs:
+          min.insync.replicas: "2"
+          max.message.bytes: 20971520
+          retention.ms: 3600000
+    - metadata:
+        name: "local-iot-events-us"
+      spec:
+        partitions: 4
+        replicas: 3
+        configs:
+          min.insync.replicas: "2"
+          max.message.bytes: 20971520
+          retention.ms: 3600000
+```