From 0a3194da09e5c82a38e9781f3c95a32e81fedf9c Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 29 Apr 2025 16:07:33 +0200
Subject: [PATCH 01/16] Improve how to deploy a collection

---
 content/deployment/how-to/deploy.md | 196 ++++++++++++++++++++--------
 1 file changed, 144 insertions(+), 52 deletions(-)

diff --git a/content/deployment/how-to/deploy.md b/content/deployment/how-to/deploy.md
index ed9f6356..df0d7092 100644
--- a/content/deployment/how-to/deploy.md
+++ b/content/deployment/how-to/deploy.md
@@ -5,141 +5,233 @@ weight: 1
 
 # How to deploy a collection
 
-This guide will help you deploy an Open Terms Archive collection to a server.
+This guide will help you deploy an Open Terms Archive collection to a server. The deployment is automated using [Ansible](https://docs.ansible.com/ansible/latest/index.html), a configuration management tool that will set up the Open Terms Archive engine and configure it to track your collection's terms.
+
+## System Overview
+
+Before diving into the deployment steps, here's a high-level overview of how Open Terms Archive works:
+
+1. **Repository structure**: Each collection uses three GitHub repositories:
+   - `declarations`: Contains the terms to track, engine configuration and deployment configuration
+   - `versions`: Automatically managed repository storing versions history
+   - `snapshots`: Automatically managed repository storing snapshots history
+
+2. **Deployment process**: The deployment is automated through GitHub Actions. Ansible configures the server and sets up the Open Terms Archive engine. On your server, [PM2](https://pm2.keymetrics.io) starts and controls the engine.
+
+3. **Operation**: The engine runs continuously on your server, periodically checking for changes in the tracked terms. When changes are detected, it automatically commits them to the versions and snapshots repositories. Email notifications are sent when issues occur.
+
+## Prerequisites
+
+Before starting, ensure you have:
+
+- A server with admin access
+- All collections repositories created, if not, see the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}})
+- At least one declaration added to your collection
+- A GitHub user account dedicated to bot-related actions (commit entries in versions and snapshots repositories, report issues when tracking fails, publish releases, …)
+- [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) installed on your local machine
+
+> **Note**: This guide is intended for both Open Terms Archive organization members and external contributors. Some steps marked with "_Specific to Open Terms Archive organization members_" are only relevant for organization members as they involve access to the organization's shared password database. External contributors should adapt these steps to their own security practices while following the same deployment principles.
 
 ## 1. Configure the server
 
 First, ensure your server provides unsupervised access:
 
-1. Check the SSH host key:
+1. Check the SSH host key and get the SSH fingerprint by running the following command on your local machine:
+
    ```shell
-   ssh-keyscan --type=ed25519 <server_address>
+   ssh-keyscan -t ed25519 <server_address>
    ```
-   If no Ed25519 key appears, generate one on the server:
+
+   If no Ed25519 key appears, generate one by running the following commands on the server:
+
    ```shell
-   sudo ssh-keygen --type=ed25519 --file=/etc/ssh/ssh_host_ed25519_key
+   sudo ssh-keygen -t ed25519 --file=/etc/ssh/ssh_host_ed25519_key
    sudo systemctl restart ssh
    ```
 
-2. Create a non-root user if needed:
+   > **Note**: A server fingerprint is a unique identifier for your server's SSH key. It helps verify that you're connecting to the correct server and not a malicious one. The fingerprint is a hash of the server's public key and is used to prevent man-in-the-middle attacks. You'll need this fingerprint in the next steps for secure deployment.
+
+2. Create a dedicated user account specifically for deployment purposes, by running the following commands on the server:
+
    ```shell
-   adduser <user>
-   usermod --append --groups=sudo <user>
+   adduser <deployment_user>
+   usermod --append --groups=sudo <deployment_user>
    ```
 
-3. Grant passwordless sudo access:
+   > **Note**: The `adduser` command might not be installed by default on your system. It can be installed with `sudo apt-get install adduser`.
+
+3. Configure sudo access for this user, by running the adding the following line to the `/etc/sudoers` file on the server:
+
    ```shell
-   # Add to /etc/sudoers:
-   <user> ALL=(ALL) NOPASSWD:ALL
+   <deployment_user> ALL=(ALL) NOPASSWD:ALL
    ```
 
+   > **Note**: While passwordless sudo access does reduce security compared to requiring a password, it is essential for full automation in deployment workflows with Ansible. The deployment process requires system-level operations (like installing packages and configuring services) that must be executed without manual intervention. To mitigate security risks, this configuration is limited to a dedicated deployment user that should only be used for deployment purposes, and the server must be properly secured with SSH key authentication.
+
 ## 2. Set up the deployment configuration
 
-1. Clone the collection declarations repository:
+1. Clone the collection declarations repository that you want to deploy:
+
    ```shell
-   git clone https://github.com/OpenTermsArchive/<collection_id>-declarations.git
+   git clone https://github.com/<organization>/<collection_id>-declarations.git
    ```
 
-2. Configure the inventory file `deployment/inventory.yml`:
+2. Configure the inventory file `deployment/inventory.yml` with your server's IP address, deployment user (from step 1), server fingerprint (from step 1) and the repository URL:
+
    ```yaml
-   <host>: "your.server.ip"
-   ansible_user: "your_username"
-   ed25519_fingerprint: "your_ssh_fingerprint"
+   <server_ip>:
+      ansible_user: <deployment_user>
+      ed25519_fingerprint: <server_ssh_fingerprint>
+      ota_source_repository: https://github.com/<organization>/<collection_id>-declarations.git
    ```
 
-3. Add the server fingerprint to GitHub:
-   - Go to `https://github.com/OpenTermsArchive/<collection_name>-declarations/settings/secrets/actions`
+3. Add the server fingerprint to GitHub, to allow the deployment workflow to uniquely identify the server:
+   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions`
    - Create a new secret named `SERVER_FINGERPRINT` with your Ed25519 fingerprint
 
 ## 3. Configure SSH deployment keys
 
-1. On the server, generate a deployment key:
+1. On the server, generate a deployment key, which will be used by the continuous deployment workflow to connect to the server to deploy the collection:
+
    ```shell
-   ssh-keygen --type=ed25519 --quiet --passphrase="" --file=~/.ssh/ota-deploy
+   ssh-keygen -t ed25519 -N "" -f ~/.ssh/ota-deploy
    cat ~/.ssh/ota-deploy.pub >> ~/.ssh/authorized_keys
    ```
 
-2. Add the private key to GitHub:
-   - Go to the repository secrets
-   - Create `SERVER_SSH_KEY` with the private key content
+2. Add the private key to GitHub, to allow the deployment workflow to connect to the server:
+   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions`
+   - Create a new secret named `SERVER_SSH_KEY` with the private key content
 
-3. Back up the keys:
-   - Store both public and private keys in the shared password database
-   - Create an entry titled "Deployment SSH key" in the collection folder
+3. > _Specific to Open Terms Archive organization members_
+   >
+   > Back up the keys in the shared password database by creating an entry titled "Deployment SSH Key" in the collection folder and storing both public and private keys in this entry
 
 ## 4. Set up GitHub permissions
 
-1. Create a fine-grained GitHub token:
-   - Log in as OTA-Bot
+1. Log in as the user account dedicated to bot-related actions in GitHub
+
+2. Create a fine-grained GitHub token:
    - Create a new token at github.com/settings/personal-access-tokens/new
-   - Set repository access for both declarations and versions repos
+   - Set repository access for both declarations and versions repositories
    - Grant "Contents" and "Issues" write permissions
 
-2. Back up the token:
-   - Store it in the shared password database under "GitHub Token"
-
 3. Get the token approved:
    - Have an organization admin approve the token request
 
-## 5. Configure secrets
+4. > _Specific to Open Terms Archive organization members_
+   >
+   > Back up the token in the shared password database by creating an entry titled "GitHub Token" in the collection folder and storing the token in this entry
+
+## 5. Configure and encrypt secrets
+
+This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_guide/index.html), a feature of Ansible that allows you to encrypt sensitive data like passwords and keys. The encrypted files can be safely committed to version control while keeping the actual secrets secure. The vault key you'll create will be used to encrypt and decrypt these secrets.
 
 1. Generate and store a vault key:
    - Generate a secure password without quotes/backticks
-   - Store it in the password database
-   - Create `deployment/vault.key` with the password
-   - Add it as `ANSIBLE_VAULT_KEY` in GitHub secrets
+   - Inside the collection folder, create `deployment/vault.key` with the password.
+   - Add the same password as `ANSIBLE_VAULT_KEY` in GitHub secrets.
 
-2. Store GitHub token:
-   ```
-   # In deployment/.env:
+   > **Note**: The same vault key is used in two places:
+   > - Locally as `vault.key` to encrypt/decrypt files during development
+   > - In GitHub Actions as `ANSIBLE_VAULT_KEY` to decrypt files during automated deployment
+
+2. Store the GitHub token (from step 4), in `deployment/.env`:
+
+   ```shell
    OTA_ENGINE_GITHUB_TOKEN=your_token
    ```
 
-3. Encrypt the `.env` file:
+3. Encrypt the `.env` file by running the following command inside the `deployment` folder of the collection:
+
    ```shell
    ansible-vault encrypt .env
    ```
 
+   > **Note**: Running the command above from the `deployment` folder will ensure that the vault.key file is used as the vault key, as this folder contains an ansible.cfg file that explicitly configures this behavior.
+   >
+   > To decrypt an encrypted file, use:
+   > ```shell
+   > ansible-vault decrypt deployment/.env
+   > ```
+   > After making changes, re-encrypt it:
+   > ```shell
+   > ansible-vault encrypt deployment/.env
+   > ```
+
+4. Commit the changes to the repository
+
+5. > _Specific to Open Terms Archive organization members_
+   >
+   > Back up the vault key in the shared password database by creating an entry titled "Vault Key" in the collection folder and storing the vault key in this entry
+
 ## 6. Set up collection-specific SSH key
 
-1. Generate a new key:
+1. Generate a new key, which will be used by the Open Terms Archive engine to perform actions on GitHub as the bot user:
+
    ```shell
-   ssh-keygen --type=ed25519 --comment=bot@opentermsarchive.org --passphrase="" --file=./<collection_name>-key
+   ssh-keygen -t ed25519 -C bot@opentermsarchive.org -N "" -f ./<collection_name>-key
    ```
 
-2. Encrypt and store the private key:
+2. Store the private key in `deployment/github-bot-private-key`
+
+3. Encrypt the private key file by running the following command inside the `deployment` folder of the collection:
+
    ```shell
-   # Copy private key to deployment/github-bot-private-key
    ansible-vault encrypt github-bot-private-key
    ```
 
-3. Add the public key to OTA-Bot's GitHub account:
+4. Commit the changes to the repository
+
+5. Add the public key to bot user's GitHub account:
    - Go to github.com/settings/ssh/new
    - Add the public key with title "<collection_name> collection"
 
+6. > _Specific to Open Terms Archive organization members_
+   >
+   > Back up the key in the shared password database by creating an entry titled "OTA-Bot GitHub SSH key" in the collection folder and storing both public and private keys in this entry
+
 ## 7. Configure email notifications
 
-1. Generate SMTP credentials:
-   - Create a new SMTP key in Brevo
-   - Name it "<collection_name> collection"
+This section describes how to configure the engine to use a specific SMTP server to send email notifications when it encounters errors during the tracking process. This helps you stay informed about issues that need attention and allows you to restart the tracking process if needed.
+
+1. Get the SMTP credentials (host, username, password) from your email provider
+
+2. Update collection SMTP configuration within the `logger` key of `@opentermsarchive/engine` in the `config/production.json` file:
+
+   ```json
+      "logger": {
+         "smtp": {
+            "host": "<smtp_host>",
+            "username": "<smtp_username>"
+         },
+      },
+   ```
+
+3. Store the password in `deployment/.env`:
 
-2. Store the credentials:
    ```shell
-   # In deployment/.env:
    OTA_ENGINE_SMTP_PASSWORD=your_smtp_key
    ```
 
-3. Encrypt the `.env` file:
+   > **Note**: To decrypt the file encrypted in a previous step in order to add the password, run `ansible-vault decrypt .env`
+
+4. Encrypt the `.env` file:
+
    ```shell
    ansible-vault encrypt .env
    ```
 
+5. > _Specific to Open Terms Archive organization members_
+   > Create a new SMTP key in Brevo and name it "<collection_name> collection"
+   > Back up the key in the shared password database by creating an entry titled "SMTP Key" in the collection folder and storing the credentials in this entry
+
 ## 8. Test the deployment
 
 1. Via GitHub Actions:
    - Check that the `deploy` action completes successfully
 
 2. Via local deployment:
+
    ```shell
    cd <collection_id>-declarations/deployment
    ansible-galaxy collection install --requirements-file requirements.yml

From dd477c4d07e206cf21c036ca199364779c0368f4 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 30 Apr 2025 10:13:30 +0200
Subject: [PATCH 02/16] Document how to manage a custom terms type

---
 .../how-to/manage-custom-terms-type.md        | 70 +++++++++++++++++++
 1 file changed, 70 insertions(+)
 create mode 100644 content/collections/how-to/manage-custom-terms-type.md

diff --git a/content/collections/how-to/manage-custom-terms-type.md b/content/collections/how-to/manage-custom-terms-type.md
new file mode 100644
index 00000000..d1e16c8d
--- /dev/null
+++ b/content/collections/how-to/manage-custom-terms-type.md
@@ -0,0 +1,70 @@
+---
+title: Manage a custom terms type
+weight: 6
+---
+
+# How to manage a custom terms type
+
+When tracking terms and conditions across different services, you might encounter situations where a service uses terms types that aren't yet supported by Open Terms Archive. 
+This guide will help you handle these custom terms types effectively, whether you're working on a new collection or expanding an existing one.
+
+## Understanding the validation
+
+Open Terms Archive validates terms types to ensure consistency and quality across collections. When you encounter a validation error like:
+
+```shell
+   1) Service declarations validation
+       <service_name>
+         valid declaration schema:
+      Error:
+
+ data/terms must be equal to one of the allowed values (in entire file)
+```
+
+This means the terms type you're trying to use isn't in the official list of supported types.
+
+## Before going further
+
+Before proceeding with using a custom terms type, please double-check that the type you're considering doesn't already exist in the supported terms types list. Different services often use different names for the same type of terms. For instance, "Terms and Conditions" might be called "Terms of Use" or "Terms of Service" by different services.
+
+Review the [supported types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) carefully to ensure the terms type you want to track is not already supported under a different name. If it does, use the associated type in your declaration. If you are sure it's not supported, you can proceed with the following steps. If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "community/how-to/join" >}}). 
+
+## Long-term solution
+
+The recommended approach is to contribute your new terms type to the official list. This helps maintain consistency across collections and enables better comparison of terms across different services.
+
+You can propose your new terms type for inclusion in the official list of supported types via the [dedicated repository](https://github.com/OpenTermsArchive/terms-types), following the [contribution process](https://github.com/OpenTermsArchive/terms-types/blob/main/CONTRIBUTING.md#add-new-terms-types).
+
+This process has the following benefits:
+
+- Your terms type becomes available to all collections
+- You don't need to maintain a custom fork
+- It helps build a more comprehensive and useful shared list
+- Enables better comparison of terms across different services
+
+This solution can take some time to have your terms type to be approved, so if you need a faster solution, you can proceed with the following temporary solutions.
+
+## Temporary solutions
+
+### For proof of concept or development
+
+As the validation is primarily intended for production environments to maintain consistency, if you're working on a proof of concept or development environment that won't be deployed to production, you can safely ignore these validation errors, the whole tracking process will still work. 
+
+### Using a forked version
+
+If you need a faster solution for production use, you can fork the terms-types repository and add your custom type:
+
+1. Fork the [terms-types repository](https://github.com/OpenTermsArchive/terms-types)
+2. Add your custom terms type to the `termsTypes.json` database file
+3. Update your collection's `package.json` to use your fork:
+
+```json
+{
+  "dependencies": {
+    "@opentermsarchive/engine": "5.0.3",
+    "@opentermsarchive/terms-types": "<your-organization-or-username>/terms-types#main"
+  }
+}
+```
+
+This solution is only recommended as a temporary solution, it is strongly recommended that you also submit the new terms type through the process describe in previous section. This way, you'll contribute to the community by helping maintain consistency across collections and enables better comparison of terms across different services, and also eventually stop maintaining a custom fork.

From abe1dd2ae46aabb09ef173ac1f1e8a7cff4d6ff0 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 30 Apr 2025 10:13:39 +0200
Subject: [PATCH 03/16] Fix weight

---
 content/collections/how-to/take-over.md | 2 +-
 content/collections/how-to/terminate.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/collections/how-to/take-over.md b/content/collections/how-to/take-over.md
index 73ac7a5e..4b970f38 100644
--- a/content/collections/how-to/take-over.md
+++ b/content/collections/how-to/take-over.md
@@ -1,6 +1,6 @@
 ---
 title: Take over a collection
-weight: 4
+weight: 5
 ---
 
 # How to take over a collection
diff --git a/content/collections/how-to/terminate.md b/content/collections/how-to/terminate.md
index a0ffc5a6..608e6cda 100644
--- a/content/collections/how-to/terminate.md
+++ b/content/collections/how-to/terminate.md
@@ -1,6 +1,6 @@
 ---
 title: Terminate a collection
-weight: 3
+weight: 4
 ---
 
 # How to terminate a collection

From 8033aec612bb11218f8213bd2f450e1d6753641d Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 30 Apr 2025 10:41:46 +0200
Subject: [PATCH 04/16] Improve how to deploy a collection

---
 content/deployment/how-to/deploy.md | 43 +++++++++++++++--------------
 1 file changed, 23 insertions(+), 20 deletions(-)

diff --git a/content/deployment/how-to/deploy.md b/content/deployment/how-to/deploy.md
index df0d7092..49928fef 100644
--- a/content/deployment/how-to/deploy.md
+++ b/content/deployment/how-to/deploy.md
@@ -5,20 +5,17 @@ weight: 1
 
 # How to deploy a collection
 
-This guide will help you deploy an Open Terms Archive collection to a server. The deployment is automated using [Ansible](https://docs.ansible.com/ansible/latest/index.html), a configuration management tool that will set up the Open Terms Archive engine and configure it to track your collection's terms.
+This guide will help you deploy an Open Terms Archive collection to a server. The deployment is automated using [Ansible](https://docs.ansible.com/ansible/latest/index.html) and will set up the Open Terms Archive engine and configure it to track your collection's terms.
 
 ## System Overview
 
-Before diving into the deployment steps, here's a high-level overview of how Open Terms Archive works:
+Before diving into the deployment steps, here's a quick reminder of the high-level overview of how Open Terms Archive works. 
 
-1. **Repository structure**: Each collection uses three GitHub repositories:
-   - `declarations`: Contains the terms to track, engine configuration and deployment configuration
-   - `versions`: Automatically managed repository storing versions history
-   - `snapshots`: Automatically managed repository storing snapshots history
+Each collection uses three repositories, `declarations` which contains the terms to track, the engine and deployment configuration, `versions` and `snapshots` which are automatically managed repositories storing versions and snapshots history.
 
-2. **Deployment process**: The deployment is automated through GitHub Actions. Ansible configures the server and sets up the Open Terms Archive engine. On your server, [PM2](https://pm2.keymetrics.io) starts and controls the engine.
+The deployment process is automated through GitHub Actions. Ansible configures the server and sets up the Open Terms Archive engine. On the server, [PM2](https://pm2.keymetrics.io) is used to start and control the engine.
 
-3. **Operation**: The engine runs continuously on your server, periodically checking for changes in the tracked terms. When changes are detected, it automatically commits them to the versions and snapshots repositories. Email notifications are sent when issues occur.
+When deployed, the engine runs continuously on the server, periodically checking for changes in the tracked terms. When changes are detected, it automatically commits them to the versions and snapshots repositories. When issues occur, email notifications are sent.
 
 ## Prerequisites
 
@@ -45,7 +42,7 @@ First, ensure your server provides unsupervised access:
    If no Ed25519 key appears, generate one by running the following commands on the server:
 
    ```shell
-   sudo ssh-keygen -t ed25519 --file=/etc/ssh/ssh_host_ed25519_key
+   sudo ssh-keygen -t ed25519 -f /etc/ssh/ssh_host_ed25519_key
    sudo systemctl restart ssh
    ```
 
@@ -60,23 +57,24 @@ First, ensure your server provides unsupervised access:
 
    > **Note**: The `adduser` command might not be installed by default on your system. It can be installed with `sudo apt-get install adduser`.
 
-3. Configure sudo access for this user, by running the adding the following line to the `/etc/sudoers` file on the server:
+3. Configure passwordless sudo access for this user, by running the adding the following line to the `/etc/sudoers` file on the server:
 
    ```shell
    <deployment_user> ALL=(ALL) NOPASSWD:ALL
    ```
 
-   > **Note**: While passwordless sudo access does reduce security compared to requiring a password, it is essential for full automation in deployment workflows with Ansible. The deployment process requires system-level operations (like installing packages and configuring services) that must be executed without manual intervention. To mitigate security risks, this configuration is limited to a dedicated deployment user that should only be used for deployment purposes, and the server must be properly secured with SSH key authentication.
+   > **Note**: While passwordless sudo access does reduce security compared to requiring a password, it is required for full automation in deployment workflows with Ansible. The deployment process requires system-level operations (like installing packages and configuring services) that must be executed without manual intervention. To mitigate security risks, this configuration is limited to a dedicated deployment user that should only be used for deployment purposes, and the server must be properly secured with SSH key authentication.
 
 ## 2. Set up the deployment configuration
 
-1. Clone the collection declarations repository that you want to deploy:
+1. Clone the collection declarations repository that you want to deploy and navigate to the collection folder:
 
    ```shell
    git clone https://github.com/<organization>/<collection_id>-declarations.git
+   cd <collection_id>-declarations
    ```
 
-2. Configure the inventory file `deployment/inventory.yml` with your server's IP address, deployment user (from step 1), server fingerprint (from step 1) and the repository URL:
+2. Configure the inventory file `deployment/inventory.yml` with your server's IP address, deployment user, server fingerprint and the repository URL:
 
    ```yaml
    <server_ip>:
@@ -115,10 +113,11 @@ First, ensure your server provides unsupervised access:
    - Set repository access for both declarations and versions repositories
    - Grant "Contents" and "Issues" write permissions
 
-3. Get the token approved:
-   - Have an organization admin approve the token request
+3. If relevant, get the token approved by having an organization admin approve the token request
 
-4. > _Specific to Open Terms Archive organization members_
+4. Keep this token for the next steps
+
+5. > _Specific to Open Terms Archive organization members_
    >
    > Back up the token in the shared password database by creating an entry titled "GitHub Token" in the collection folder and storing the token in this entry
 
@@ -128,14 +127,15 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
 
 1. Generate and store a vault key:
    - Generate a secure password without quotes/backticks
-   - Inside the collection folder, create `deployment/vault.key` with the password.
-   - Add the same password as `ANSIBLE_VAULT_KEY` in GitHub secrets.
+   - Inside the collection folder, create a file named `deployment/vault.key` and paste the generated password into it.
+   - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions`
+   - Create a new secret named `ANSIBLE_VAULT_KEY` and paste the same password into it.
 
    > **Note**: The same vault key is used in two places:
    > - Locally as `vault.key` to encrypt/decrypt files during development
    > - In GitHub Actions as `ANSIBLE_VAULT_KEY` to decrypt files during automated deployment
 
-2. Store the GitHub token (from step 4), in `deployment/.env`:
+2. Store the GitHub token, generated in the previous section, in `deployment/.env`:
 
    ```shell
    OTA_ENGINE_GITHUB_TOKEN=your_token
@@ -147,13 +147,16 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
    ansible-vault encrypt .env
    ```
 
-   > **Note**: Running the command above from the `deployment` folder will ensure that the vault.key file is used as the vault key, as this folder contains an ansible.cfg file that explicitly configures this behavior.
+   > **Note**: Running the command from the `deployment` folder will ensure that the `vault.key` file is used as vault key, since this folder contains an `ansible.cfg` file that explicitly configures this behavior.
    >
    > To decrypt an encrypted file, use:
+   >
    > ```shell
    > ansible-vault decrypt deployment/.env
    > ```
+   >
    > After making changes, re-encrypt it:
+   >
    > ```shell
    > ansible-vault encrypt deployment/.env
    > ```

From 115e36ef1e185de3bd35657a57e72c606c174858 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 09:10:33 +0200
Subject: [PATCH 05/16] Apply suggestions from code review

Improve wording

Co-authored-by: Matti Schneider <matti@opentermsarchive.org>
---
 content/collections/how-to/manage-custom-terms-type.md | 6 +++---
 content/deployment/how-to/deploy.md                    | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/content/collections/how-to/manage-custom-terms-type.md b/content/collections/how-to/manage-custom-terms-type.md
index d1e16c8d..83a2fb20 100644
--- a/content/collections/how-to/manage-custom-terms-type.md
+++ b/content/collections/how-to/manage-custom-terms-type.md
@@ -31,9 +31,9 @@ Review the [supported types list](https://github.com/OpenTermsArchive/terms-type
 
 ## Long-term solution
 
-The recommended approach is to contribute your new terms type to the official list. This helps maintain consistency across collections and enables better comparison of terms across different services.
+The recommended approach is to contribute your new terms type to the official list. This enables collections interoperability and comparison of terms across different services.
 
-You can propose your new terms type for inclusion in the official list of supported types via the [dedicated repository](https://github.com/OpenTermsArchive/terms-types), following the [contribution process](https://github.com/OpenTermsArchive/terms-types/blob/main/CONTRIBUTING.md#add-new-terms-types).
+You can suggest new terms type for the official list via the dedicated [contribution process](https://github.com/OpenTermsArchive/terms-types/blob/main/CONTRIBUTING.md#add-new-terms-types).
 
 This process has the following benefits:
 
@@ -42,7 +42,7 @@ This process has the following benefits:
 - It helps build a more comprehensive and useful shared list
 - Enables better comparison of terms across different services
 
-This solution can take some time to have your terms type to be approved, so if you need a faster solution, you can proceed with the following temporary solutions.
+Inclusion in the official terms types list has a delay for consensus building. In the meantime, you can proceed with the following temporary solutions.
 
 ## Temporary solutions
 
diff --git a/content/deployment/how-to/deploy.md b/content/deployment/how-to/deploy.md
index 49928fef..ed1ce7dd 100644
--- a/content/deployment/how-to/deploy.md
+++ b/content/deployment/how-to/deploy.md
@@ -24,7 +24,7 @@ Before starting, ensure you have:
 - A server with admin access
 - All collections repositories created, if not, see the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}})
 - At least one declaration added to your collection
-- A GitHub user account dedicated to bot-related actions (commit entries in versions and snapshots repositories, report issues when tracking fails, publish releases, …)
+- A GitHub user account to automate actions such as committing entries in versions and snapshots repositories, reporting issues when tracking fails, publishing releases…
 - [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) installed on your local machine
 
 > **Note**: This guide is intended for both Open Terms Archive organization members and external contributors. Some steps marked with "_Specific to Open Terms Archive organization members_" are only relevant for organization members as they involve access to the organization's shared password database. External contributors should adapt these steps to their own security practices while following the same deployment principles.
@@ -57,7 +57,7 @@ First, ensure your server provides unsupervised access:
 
    > **Note**: The `adduser` command might not be installed by default on your system. It can be installed with `sudo apt-get install adduser`.
 
-3. Configure passwordless sudo access for this user, by running the adding the following line to the `/etc/sudoers` file on the server:
+3. Configure passwordless sudo access for this user, by adding the following line to the `/etc/sudoers` file on the server:
 
    ```shell
    <deployment_user> ALL=(ALL) NOPASSWD:ALL

From bc04f4a6e47e223d6653d62e0e82328dc1f840ea Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 10:11:57 +0200
Subject: [PATCH 06/16] Improve how to manage a custom terms type

---
 .../how-to/manage-custom-terms-type.md        | 32 +++----------------
 1 file changed, 5 insertions(+), 27 deletions(-)

diff --git a/content/collections/how-to/manage-custom-terms-type.md b/content/collections/how-to/manage-custom-terms-type.md
index 83a2fb20..f03f5235 100644
--- a/content/collections/how-to/manage-custom-terms-type.md
+++ b/content/collections/how-to/manage-custom-terms-type.md
@@ -5,29 +5,14 @@ weight: 6
 
 # How to manage a custom terms type
 
-When tracking terms and conditions across different services, you might encounter situations where a service uses terms types that aren't yet supported by Open Terms Archive. 
+When tracking terms and conditions across different services, you might encounter situations where a service uses terms types that aren't yet supported by Open Terms Archive.
 This guide will help you handle these custom terms types effectively, whether you're working on a new collection or expanding an existing one.
 
-## Understanding the validation
-
-Open Terms Archive validates terms types to ensure consistency and quality across collections. When you encounter a validation error like:
-
-```shell
-   1) Service declarations validation
-       <service_name>
-         valid declaration schema:
-      Error:
-
- data/terms must be equal to one of the allowed values (in entire file)
-```
-
-This means the terms type you're trying to use isn't in the official list of supported types.
-
-## Before going further
+## Prerequisites
 
 Before proceeding with using a custom terms type, please double-check that the type you're considering doesn't already exist in the supported terms types list. Different services often use different names for the same type of terms. For instance, "Terms and Conditions" might be called "Terms of Use" or "Terms of Service" by different services.
 
-Review the [supported types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) carefully to ensure the terms type you want to track is not already supported under a different name. If it does, use the associated type in your declaration. If you are sure it's not supported, you can proceed with the following steps. If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "community/how-to/join" >}}). 
+Review the [supported types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) carefully to ensure the terms type you want to track is not already supported under a different name. If it does, use the associated type in your declaration. If you are sure it's not supported, you can proceed with the following steps. If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "community/how-to/join" >}}).
 
 ## Long-term solution
 
@@ -35,20 +20,13 @@ The recommended approach is to contribute your new terms type to the official li
 
 You can suggest new terms type for the official list via the dedicated [contribution process](https://github.com/OpenTermsArchive/terms-types/blob/main/CONTRIBUTING.md#add-new-terms-types).
 
-This process has the following benefits:
-
-- Your terms type becomes available to all collections
-- You don't need to maintain a custom fork
-- It helps build a more comprehensive and useful shared list
-- Enables better comparison of terms across different services
-
 Inclusion in the official terms types list has a delay for consensus building. In the meantime, you can proceed with the following temporary solutions.
 
 ## Temporary solutions
 
 ### For proof of concept or development
 
-As the validation is primarily intended for production environments to maintain consistency, if you're working on a proof of concept or development environment that won't be deployed to production, you can safely ignore these validation errors, the whole tracking process will still work. 
+As the validation is primarily intended for production environments to maintain consistency, if you're working on a proof of concept or development environment that won't be deployed to production, you can safely ignore terms types validation errors, the whole tracking process will still work.
 
 ### Using a forked version
 
@@ -67,4 +45,4 @@ If you need a faster solution for production use, you can fork the terms-types r
 }
 ```
 
-This solution is only recommended as a temporary solution, it is strongly recommended that you also submit the new terms type through the process describe in previous section. This way, you'll contribute to the community by helping maintain consistency across collections and enables better comparison of terms across different services, and also eventually stop maintaining a custom fork.
+This solution is only recommended as a **temporary** solution, it is strongly recommended that you also submit the new terms type through the process describe in previous section. This way, you'll contribute to the community by helping maintain consistency across collections and enables better comparison of terms across different services, and also eventually stop maintaining a custom fork.

From 949df7c971dcf14eeea171b43c7a1657b22e9a24 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 11:41:48 +0200
Subject: [PATCH 07/16] Fix hover color for footer links

---
 themes/opentermsarchive/assets/css/components/footer.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/themes/opentermsarchive/assets/css/components/footer.css b/themes/opentermsarchive/assets/css/components/footer.css
index 81aaf645..dd7631c1 100644
--- a/themes/opentermsarchive/assets/css/components/footer.css
+++ b/themes/opentermsarchive/assets/css/components/footer.css
@@ -15,6 +15,10 @@
       & a {
         display: inline-flex;
         color: var(--colorBlack600);
+
+        &:hover {
+          color: var(--colorSecondary);
+        }
       }
     }
   }

From e62abd9ea971434a9808e17e330745e1543c42b0 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 11:42:56 +0200
Subject: [PATCH 08/16] Increase footer menu items spacing for readability

---
 themes/opentermsarchive/assets/css/components/footer.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/themes/opentermsarchive/assets/css/components/footer.css b/themes/opentermsarchive/assets/css/components/footer.css
index dd7631c1..fdacc00d 100644
--- a/themes/opentermsarchive/assets/css/components/footer.css
+++ b/themes/opentermsarchive/assets/css/components/footer.css
@@ -33,7 +33,7 @@
 }
 
 .footer__main-menu {
-  gap: var(--m2XS) var(--mS);
+  gap: var(--m2XS) var(--mM);
 }
 
 .footer__sub-menu {

From 380f03e0c3449f4bd7678380da56ccb30da62f16 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 11:43:55 +0200
Subject: [PATCH 09/16] Fix english grammar

---
 config/_default/menus.en.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/_default/menus.en.yaml b/config/_default/menus.en.yaml
index 6860886f..aee7adcf 100644
--- a/config/_default/menus.en.yaml
+++ b/config/_default/menus.en.yaml
@@ -36,7 +36,7 @@ footer:
   - name: About
     url: https://opentermsarchive.org/en/about/
     weight: 7
-  - name: Contact-us
+  - name: Contact us
     identifier: mailto
     weight: 8
 footer_sub:

From 409bffcd798b59768e98ec9c13be084daf7c5b01 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 11:44:42 +0200
Subject: [PATCH 10/16] Add shortcode to show content by query param

---
 .../assets/css/components/textContent.css         |  5 +++++
 .../opentermsarchive/layouts/_default/baseof.html |  2 ++
 .../layouts/partials/showIfParam.html             | 15 +++++++++++++++
 .../layouts/shortcodes/showIfParam.html           |  5 +++++
 4 files changed, 27 insertions(+)
 create mode 100644 themes/opentermsarchive/layouts/partials/showIfParam.html
 create mode 100644 themes/opentermsarchive/layouts/shortcodes/showIfParam.html

diff --git a/themes/opentermsarchive/assets/css/components/textContent.css b/themes/opentermsarchive/assets/css/components/textContent.css
index a00c84ab..8f688070 100644
--- a/themes/opentermsarchive/assets/css/components/textContent.css
+++ b/themes/opentermsarchive/assets/css/components/textContent.css
@@ -171,6 +171,11 @@
     }
   }
 
+  & ol + ol,
+  & ul + ul {
+    margin-top: calc(var(--mL) * -1);
+  }
+
   & li {
     position: relative;
     margin-bottom: var(--m2XS);
diff --git a/themes/opentermsarchive/layouts/_default/baseof.html b/themes/opentermsarchive/layouts/_default/baseof.html
index 0bc670b9..4b01ea11 100644
--- a/themes/opentermsarchive/layouts/_default/baseof.html
+++ b/themes/opentermsarchive/layouts/_default/baseof.html
@@ -11,6 +11,8 @@
         {{ partial "footer.html" . }}
 
         {{ partial "sprite.svg" . }}
+
+        {{ partial "showIfParam.html" . }}
     </body>
 
 </html>
diff --git a/themes/opentermsarchive/layouts/partials/showIfParam.html b/themes/opentermsarchive/layouts/partials/showIfParam.html
new file mode 100644
index 00000000..2da64fe1
--- /dev/null
+++ b/themes/opentermsarchive/layouts/partials/showIfParam.html
@@ -0,0 +1,15 @@
+<script>
+    document.addEventListener('DOMContentLoaded', function() {
+        const urlParams = new URLSearchParams(window.location.search);
+        const elements = document.querySelectorAll('[show-if-param-content]');
+        
+        elements.forEach(element => {
+            const param = element.dataset.param;
+            const value = element.dataset.value;
+            
+            if (urlParams.get(param) === value) {
+                element.removeAttribute('style');
+            }
+        });
+    });
+</script>
diff --git a/themes/opentermsarchive/layouts/shortcodes/showIfParam.html b/themes/opentermsarchive/layouts/shortcodes/showIfParam.html
new file mode 100644
index 00000000..8bf217b6
--- /dev/null
+++ b/themes/opentermsarchive/layouts/shortcodes/showIfParam.html
@@ -0,0 +1,5 @@
+{{ $param := .Get 0 }}
+{{ $value := .Get 1 | default "true" }}
+{{ $content := .Inner | markdownify }}
+{{ $content = replaceRE `<([^>]+)>` (printf `<$1 show-if-param-content data-param="%s" data-value="%s" style="display: none;">` $param $value) $content }}
+{{ $content | safeHTML }}

From 4dbf569e59289c64c6b129575f0bb8b692810fa5 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 14:44:16 +0200
Subject: [PATCH 11/16] Explain terms types

---
 content/terms/explanation/terms-types.md | 54 ++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 content/terms/explanation/terms-types.md

diff --git a/content/terms/explanation/terms-types.md b/content/terms/explanation/terms-types.md
new file mode 100644
index 00000000..ceaefda7
--- /dev/null
+++ b/content/terms/explanation/terms-types.md
@@ -0,0 +1,54 @@
+---
+title: "Understanding terms types"
+linkTitle: Terms types
+weight: 1
+---
+
+# Terms types: a foundation of a consistent archive
+
+## What are terms types?
+
+Terms types are standardized categories that classify the different kinds of terms and conditions documents, serving as a common language for organizing and comparing terms across services.
+
+## Why standardized terms types are needed
+
+Services often use different names for the same type of terms. For instance, "Terms and Conditions" might be called "Terms of Use" or "Terms of Service" by different services. This kind of inconsistency creates significant challenges in finding and comparing similar terms documents across different services. It also makes it difficult to maintain a consistent structure in all collections, and to ensure a comprehensive coverage of all legal documents. 
+
+Without standardization, activists, journalists, researchers, lawmakers and regulators struggle to track changes, conduct comparative analyses, and maintain organized collections of terms. Standardized terms types serve as a common language that bridges these naming variations, enabling more efficient organization, improved searchability, and clearer understanding of the legal landscape across different services.
+
+## How Open Terms Archive handles terms types
+
+Open Terms Archive maintains an [official list of terms types](https://github.com/OpenTermsArchive/terms-types) that serves as a reference for all collections. This standardization is used for automated validation of service declarations, ensuring that all terms are properly categorized.
+
+When you encounter a validation error related to terms type, it looks like this:
+
+```shell
+   1) Service declarations validation
+       <service_name>
+         valid declaration schema:
+      Error:
+
+ data/terms must be equal to one of the allowed values (in entire file)
+```
+
+This means the terms type you're trying to use isn't in the official list of supported types.
+
+## When a new terms type needs to be suggested
+
+Situations may arise where a terms type used by a service is not yet included in the official list. Such situations typically occur when:
+
+- A document is specific to a domain that is not yet covered by Open Terms Archive collections
+- A service uses a unique name for their document
+- A new type of document emerges in the digital landscape
+- A service combines multiple documents in an unusual way
+
+## What are the benefits of contributing new terms types
+
+When a new terms type is suggested to the Open Terms Archive community and accepted, it contributes to a larger ecosystem and has the following benefits:
+
+- It makes the new terms type available to all collections
+- It eliminates the need for custom solutions or forks for validating terms types
+- It helps build a more comprehensive shared vocabulary
+- It enables better comparison and analysis of terms across services
+
+To contribute a new terms type, follow the [contribution process](https://github.com/OpenTermsArchive/terms-types/blob/main/CONTRIBUTING.md#add-new-terms-types) in the `terms-types` repository.

From 3312601b645c9ea2906c49583ef80348e4cfe54a Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 14:48:27 +0200
Subject: [PATCH 12/16] Move and improve guide to manage custom terms type

---
 .../how-to/manage-custom-terms-type.md              | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)
 rename content/{collections => terms}/how-to/manage-custom-terms-type.md (84%)

diff --git a/content/collections/how-to/manage-custom-terms-type.md b/content/terms/how-to/manage-custom-terms-type.md
similarity index 84%
rename from content/collections/how-to/manage-custom-terms-type.md
rename to content/terms/how-to/manage-custom-terms-type.md
index f03f5235..871f1d30 100644
--- a/content/collections/how-to/manage-custom-terms-type.md
+++ b/content/terms/how-to/manage-custom-terms-type.md
@@ -1,18 +1,25 @@
 ---
 title: Manage a custom terms type
-weight: 6
+weight: 4
 ---
 
 # How to manage a custom terms type
 
-When tracking terms and conditions across different services, you might encounter situations where a service uses terms types that aren't yet supported by Open Terms Archive.
+When tracking terms and conditions across different services, you might encounter situations where a service uses terms types that aren't yet supported by Open Terms Archive. 
+
 This guide will help you handle these custom terms types effectively, whether you're working on a new collection or expanding an existing one.
 
+_To better understand what terms types are and how they work, you can read our [detailed explanation]({{< relref "terms/explanation/terms-types" >}})._
+
 ## Prerequisites
 
 Before proceeding with using a custom terms type, please double-check that the type you're considering doesn't already exist in the supported terms types list. Different services often use different names for the same type of terms. For instance, "Terms and Conditions" might be called "Terms of Use" or "Terms of Service" by different services.
 
-Review the [supported types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) carefully to ensure the terms type you want to track is not already supported under a different name. If it does, use the associated type in your declaration. If you are sure it's not supported, you can proceed with the following steps. If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "community/how-to/join" >}}).
+Review the [supported types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) carefully to ensure the terms type you want to track is not already supported under a different name:
+
+- If it does, use the associated type in your declaration.
+- If you are sure it's not supported, you can proceed with the following steps.
+- If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "community/how-to/join" >}}).
 
 ## Long-term solution
 

From 532d689a4f4bb64b7d1fbdb33b328af23fef53b5 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 14:49:23 +0200
Subject: [PATCH 13/16] Improve how content specific to ota members is handled

---
 content/deployment/how-to/deploy.md | 33 ++++++++++++++---------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/content/deployment/how-to/deploy.md b/content/deployment/how-to/deploy.md
index ed1ce7dd..ab9a94e4 100644
--- a/content/deployment/how-to/deploy.md
+++ b/content/deployment/how-to/deploy.md
@@ -27,8 +27,6 @@ Before starting, ensure you have:
 - A GitHub user account to automate actions such as committing entries in versions and snapshots repositories, reporting issues when tracking fails, publishing releases…
 - [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) installed on your local machine
 
-> **Note**: This guide is intended for both Open Terms Archive organization members and external contributors. Some steps marked with "_Specific to Open Terms Archive organization members_" are only relevant for organization members as they involve access to the organization's shared password database. External contributors should adapt these steps to their own security practices while following the same deployment principles.
-
 ## 1. Configure the server
 
 First, ensure your server provides unsupervised access:
@@ -100,9 +98,9 @@ First, ensure your server provides unsupervised access:
    - Go to `https://github.com/<organization>/<collection_id>-declarations/settings/secrets/actions`
    - Create a new secret named `SERVER_SSH_KEY` with the private key content
 
-3. > _Specific to Open Terms Archive organization members_
-   >
-   > Back up the keys in the shared password database by creating an entry titled "Deployment SSH Key" in the collection folder and storing both public and private keys in this entry
+{{< showIfParam "ota" >}}
+3. Back up the keys in the shared password database by creating an entry titled "Deployment SSH Key" in the collection folder and storing both public and private keys in this entry
+{{< /showIfParam >}}
 
 ## 4. Set up GitHub permissions
 
@@ -117,9 +115,9 @@ First, ensure your server provides unsupervised access:
 
 4. Keep this token for the next steps
 
-5. > _Specific to Open Terms Archive organization members_
-   >
-   > Back up the token in the shared password database by creating an entry titled "GitHub Token" in the collection folder and storing the token in this entry
+{{< showIfParam "ota" >}}
+5. Back up the token in the shared password database by creating an entry titled "GitHub Token" in the collection folder and storing the token in this entry
+{{< /showIfParam >}}
 
 ## 5. Configure and encrypt secrets
 
@@ -163,9 +161,9 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
 
 4. Commit the changes to the repository
 
-5. > _Specific to Open Terms Archive organization members_
-   >
-   > Back up the vault key in the shared password database by creating an entry titled "Vault Key" in the collection folder and storing the vault key in this entry
+{{< showIfParam "ota" >}}
+5. Back up the vault key in the shared password database by creating an entry titled "Vault Key" in the collection folder and storing the vault key in this entry
+{{< /showIfParam >}}
 
 ## 6. Set up collection-specific SSH key
 
@@ -189,9 +187,9 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
    - Go to github.com/settings/ssh/new
    - Add the public key with title "<collection_name> collection"
 
-6. > _Specific to Open Terms Archive organization members_
-   >
-   > Back up the key in the shared password database by creating an entry titled "OTA-Bot GitHub SSH key" in the collection folder and storing both public and private keys in this entry
+{{< showIfParam "ota" >}}
+6. Back up the key in the shared password database by creating an entry titled "OTA-Bot GitHub SSH key" in the collection folder and storing both public and private keys in this entry
+{{< /showIfParam >}}
 
 ## 7. Configure email notifications
 
@@ -224,9 +222,10 @@ This section describes how to configure the engine to use a specific SMTP server
    ansible-vault encrypt .env
    ```
 
-5. > _Specific to Open Terms Archive organization members_
-   > Create a new SMTP key in Brevo and name it "<collection_name> collection"
-   > Back up the key in the shared password database by creating an entry titled "SMTP Key" in the collection folder and storing the credentials in this entry
+{{< showIfParam "ota" >}}
+5. Create a new SMTP key in Brevo and name it "<collection_name> collection"
+6. Back up the key in the shared password database by creating an entry titled "SMTP Key" in the collection folder and storing the credentials in this entry
+{{< /showIfParam >}}
 
 ## 8. Test the deployment
 

From 2a23b6d8ecc35f30c3c4d6e49cc55588df7b794a Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 16:27:49 +0200
Subject: [PATCH 14/16] Create a reference for Deployment architecture

---
 content/deployment/how-to/deploy.md           | 11 +--
 content/deployment/reference/architecture.md  | 84 +++++++++++++++++++
 .../reference/server-specifications.md        |  2 +-
 3 files changed, 86 insertions(+), 11 deletions(-)
 create mode 100644 content/deployment/reference/architecture.md

diff --git a/content/deployment/how-to/deploy.md b/content/deployment/how-to/deploy.md
index ab9a94e4..0c26527d 100644
--- a/content/deployment/how-to/deploy.md
+++ b/content/deployment/how-to/deploy.md
@@ -7,20 +7,11 @@ weight: 1
 
 This guide will help you deploy an Open Terms Archive collection to a server. The deployment is automated using [Ansible](https://docs.ansible.com/ansible/latest/index.html) and will set up the Open Terms Archive engine and configure it to track your collection's terms.
 
-## System Overview
-
-Before diving into the deployment steps, here's a quick reminder of the high-level overview of how Open Terms Archive works. 
-
-Each collection uses three repositories, `declarations` which contains the terms to track, the engine and deployment configuration, `versions` and `snapshots` which are automatically managed repositories storing versions and snapshots history.
-
-The deployment process is automated through GitHub Actions. Ansible configures the server and sets up the Open Terms Archive engine. On the server, [PM2](https://pm2.keymetrics.io) is used to start and control the engine.
-
-When deployed, the engine runs continuously on the server, periodically checking for changes in the tracked terms. When changes are detected, it automatically commits them to the versions and snapshots repositories. When issues occur, email notifications are sent.
-
 ## Prerequisites
 
 Before starting, ensure you have:
 
+- A basic understanding of the [deployment architecture]({{< relref "deployment/reference/architecture" >}})
 - A server with admin access
 - All collections repositories created, if not, see the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}})
 - At least one declaration added to your collection
diff --git a/content/deployment/reference/architecture.md b/content/deployment/reference/architecture.md
new file mode 100644
index 00000000..cb52c044
--- /dev/null
+++ b/content/deployment/reference/architecture.md
@@ -0,0 +1,84 @@
+---
+title: Deployment architecture
+linkTitle: Architecture
+weight: 1
+---
+
+# Deployment architecture
+
+This document provides an overview of the key components and elements involved in the deployment process of a collection.
+
+## Repository structure
+
+A collection is defined by three repositories that work together to manage and track terms.
+
+The declarations repository, `<collection_name>-declarations`, serves as the primary workspace for collection maintainers, containing declarations of the terms to track along with engine and deployment configurations.
+
+This repository is complemented by two automatically managed repositories:
+
+- The versions repository, `<collection_name>-versions`, which maintains a chronological history of terms changes in their readable format
+- The snapshots repository, `<collection_name>-snapshots`, which maintains a chronological history of the original source document (HTML, PDF…) from which the terms will be extracted
+
+These repositories must be considered as databases and are automatically updated by the engine whenever changes are detected in the tracked terms.
+
+## Infrastructure
+
+The server is where the Open Terms Archive engine runs.
+
+The server requires administrative access to allow setting up the system in the appropriate state.
+
+It has an Ed25519 SSH host key pair, `ssh_host_ed25519_key`, which provides a unique server fingerprint, `<server_ssh_fingerprint>`, for identity verification.
+
+There is also a dedicated deployment user account, `<deployment_user>`, with passwordless sudo access to facilitate automated deployment tasks while maintaining security.
+
+Process management is handled through [PM2](https://pm2.keymetrics.io/) and ensures the Open Terms Archive engine runs continuously and reliably.
+
+The engine itself is the core application that performs the actual term tracking and repository management tasks.
+
+## Security elements
+
+### Authentication
+
+Security is maintained through multiple layers of authentication.
+
+The server's SSH host key pair, `ssh_host_ed25519_key`, generates a unique server fingerprint, `<server_ssh_fingerprint>`. This fingerprint verifies server identity and prevents man-in-the-middle attacks during deployment.
+
+The deployment process uses a dedicated SSH key pair, `ota-deploy`, for secure server connections during the continuous deployment workflow.
+
+A separate collection-specific SSH key pair, `<collection_name>-key`, enables the engine to perform GitHub actions as a bot user.
+
+Access to GitHub repositories is controlled through a fine-grained access token, `OTA_ENGINE_GITHUB_TOKEN`, that provides specific permissions for repository management.
+
+### Secret management
+
+Sensitive information is protected by the [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_guide/index.html) encryption system.
+
+The vault system uses a master password, `vault.key` to encrypt and decrypt sensitive data. This includes the environment configuration file, `.env`, and the GitHub bot's private key, `github-bot-private-key`, ensuring that sensitive credentials remain secure while still being accessible to the deployment process.
+
+## Automation tools
+
+[GitHub Actions](https://docs.github.com/en/actions) and [Ansible](https://www.ansible.com/) automate the deployment process. GitHub Actions runs the workflow while Ansible configures the server and deploys the engine.
+
+A dedicated GitHub user account is used for bot-related actions such as committing entries in versions and snapshots repositories, reporting issues when tracking fails, and publishing releases. This account is configured with specific permissions to perform these automated tasks.
+
+The engine sends email notifications to collection administrators when errors or issues occur during the tracking process, enabling prompt intervention when needed.
+
+The engine automatically creates issues in the declarations repository to notify collection maintainers when terms can no longer be tracked. These issues provide details about the tracking failure to allow maintainers to investigate and resolve the problem.
+
+## Configuration files
+
+The system's behavior is controlled through several key configuration files:
+
+- `inventory.yml`: Defines server address and deployment parameters
+- `production.json`: Stores application-specific settings
+- `vault.key`: Protects sensitive data through encryption
+
+## Maintenance
+
+The Open Terms Archive system is designed for continuous operation with minimal intervention.
+
+The engine automatically tracks changes in terms, commits updates to the appropriate repositories, reports issues and sends notifications when issues occur.
+
+System health is maintained through PM2's process management capabilities.
+
+Regular administrative maintenance involves updating collections dependencies such as engine and deployment recipes. It also includes monitoring email notifications and reviewing application logs in case of issues or tracking interruptions.
diff --git a/content/deployment/reference/server-specifications.md b/content/deployment/reference/server-specifications.md
index 1e389a99..29e5a0e5 100644
--- a/content/deployment/reference/server-specifications.md
+++ b/content/deployment/reference/server-specifications.md
@@ -1,6 +1,6 @@
 ---
 title: Server specifications
-weight: 1
+weight: 2
 ---
 
 # Server specifications

From f6c4616e4cfbb4a7d7ccba4efb737a3232857c71 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Tue, 6 May 2025 17:39:13 +0200
Subject: [PATCH 15/16] Improve showIfParam shortcode

---
 .../assets/css/components/showIfParam.css     |  3 +++
 themes/opentermsarchive/assets/css/loader.css |  1 +
 .../layouts/shortcodes/showIfParam.html       | 19 +++++++++++++++++++
 3 files changed, 23 insertions(+)
 create mode 100644 themes/opentermsarchive/assets/css/components/showIfParam.css

diff --git a/themes/opentermsarchive/assets/css/components/showIfParam.css b/themes/opentermsarchive/assets/css/components/showIfParam.css
new file mode 100644
index 00000000..b2f5463b
--- /dev/null
+++ b/themes/opentermsarchive/assets/css/components/showIfParam.css
@@ -0,0 +1,3 @@
+[show-if-param-content] {
+  background-color: rgb(231, 248, 255);
+}
diff --git a/themes/opentermsarchive/assets/css/loader.css b/themes/opentermsarchive/assets/css/loader.css
index 49d9e6fe..387765fa 100644
--- a/themes/opentermsarchive/assets/css/loader.css
+++ b/themes/opentermsarchive/assets/css/loader.css
@@ -36,3 +36,4 @@
 @import "/components/textContent.css";
 @import "/components/aside.css";
 @import "/components/refItem.css";
+@import "/components/showIfParam.css";
diff --git a/themes/opentermsarchive/layouts/shortcodes/showIfParam.html b/themes/opentermsarchive/layouts/shortcodes/showIfParam.html
index 8bf217b6..55d0767d 100644
--- a/themes/opentermsarchive/layouts/shortcodes/showIfParam.html
+++ b/themes/opentermsarchive/layouts/shortcodes/showIfParam.html
@@ -1,3 +1,22 @@
+{{/* 
+  Shortcode: showIfParam
+  Description: Shows content conditionally based on a URL parameter value.
+  
+  Usage:
+  {{% showIfParam "paramName" "expectedValue" %}}
+  Content to show when paramName=expectedValue
+  {{% /showIfParam %}}
+  
+  Parameters:
+  - paramName: The URL parameter to check (required)
+  - expectedValue: The value to match against (optional, defaults to "true")
+  
+  Example:
+  {{% showIfParam "feature" "beta" %}}
+  This content will only show when URL has ?feature=beta
+  {{% /showIfParam %}}
+*/}}
+
 {{ $param := .Get 0 }}
 {{ $value := .Get 1 | default "true" }}
 {{ $content := .Inner | markdownify }}

From dc53468d1ef19d884838fd0041f969d7b6680e1b Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 7 May 2025 09:08:11 +0200
Subject: [PATCH 16/16] Improve CSS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Clément Biron <clement.biron@gmail.com>
---
 themes/opentermsarchive/assets/css/components/showIfParam.css | 2 +-
 themes/opentermsarchive/assets/css/components/textContent.css | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/themes/opentermsarchive/assets/css/components/showIfParam.css b/themes/opentermsarchive/assets/css/components/showIfParam.css
index b2f5463b..56ffc941 100644
--- a/themes/opentermsarchive/assets/css/components/showIfParam.css
+++ b/themes/opentermsarchive/assets/css/components/showIfParam.css
@@ -1,3 +1,3 @@
 [show-if-param-content] {
-  background-color: rgb(231, 248, 255);
+  background-color: color-mix(in srgb, var(--colorPrimary) 10%, var(--colorWhite));
 }
diff --git a/themes/opentermsarchive/assets/css/components/textContent.css b/themes/opentermsarchive/assets/css/components/textContent.css
index 8f688070..58cc7ab7 100644
--- a/themes/opentermsarchive/assets/css/components/textContent.css
+++ b/themes/opentermsarchive/assets/css/components/textContent.css
@@ -173,7 +173,7 @@
 
   & ol + ol,
   & ul + ul {
-    margin-top: calc(var(--mL) * -1);
+    margin-top: calc((var(--mL) * -1) + var(--m2XS));
   }
 
   & li {