From 900f77321f9de4d5325c6a80e5ef613daf0b3e20 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Thu, 27 Mar 2025 10:36:42 +0100
Subject: [PATCH 01/20] Improve configOption

---
 content/api/cli.md                            | 32 ++++-----
 .../collections/reference/configuration.md    | 70 +++++++++----------
 .../reference/environment-variables.md        | 12 ++--
 content/collections/reference/metadata.md     | 70 ++++++++++---------
 .../assets/css/components/configOption.css    | 24 ++++++-
 .../layouts/shortcodes/configOption.html      | 41 +++++++----
 6 files changed, 142 insertions(+), 107 deletions(-)

diff --git a/content/api/cli.md b/content/api/cli.md
index c858ebd6..f8ee9cdc 100644
--- a/content/api/cli.md
+++ b/content/api/cli.md
@@ -14,50 +14,50 @@ In these commands:
 
 ## Tracking terms
 
-{{< configOption name="ota track" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="`npx ota track`" >}}
+{{< configOption name="ota track" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="`npx ota track`" />}}
 
 > Note that the snapshots and versions will be recorded at the moment the command is executed, on top of the existing local history. If a shared history already exists and the goal is to add on top of it, that history has to be downloaded before executing that command.
 
-{{< configOption name="ota track --help" description="Show help and available options for track command" example="`npx ota track --help`" >}}
+{{< configOption name="ota track --help" description="Show help and available options for track command" example="`npx ota track --help`" />}}
 
-{{< configOption name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\"`" >}}
+{{< configOption name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\"`" />}}
 
-{{< configOption name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" >}}
+{{< configOption name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" />}}
 
-{{< configOption name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="`npx ota track --schedule`" >}}
+{{< configOption name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="`npx ota track --schedule`" />}}
 
 ## Validating declarations
 
-{{< configOption name="ota validate [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="`npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" >}}
+{{< configOption name="ota validate [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="`npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" />}}
 
-{{< configOption name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="`npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" >}}
+{{< configOption name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="`npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" />}}
 
-{{< configOption name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="`npx ota validate --modified`" >}}
+{{< configOption name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="`npx ota validate --modified`" />}}
 
 ## Linting declarations
 
-{{< configOption name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="`npx ota lint --services \"Facebook\" \"LinkedIn\"`" >}}
+{{< configOption name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="`npx ota lint --services \"Facebook\" \"LinkedIn\"`" />}}
 
-{{< configOption name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="`npx ota lint --fix`" >}}
+{{< configOption name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="`npx ota lint --fix`" />}}
 
-{{< configOption name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="`npx ota lint --modified`" >}}
+{{< configOption name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="`npx ota lint --modified`" />}}
 
 ## Publishing dataset
 
-{{< configOption name="ota dataset [--file <filename>]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="`npx ota dataset --file dataset.zip`" >}}
+{{< configOption name="ota dataset [--file <filename>]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="`npx ota dataset --file dataset.zip`" />}}
 
 To export the dataset into a ZIP file and publish it on GitHub releases:
 
-{{< configOption name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish`" >}}
+{{< configOption name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish`" />}}
 
 The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/reference/environment-variables" >}}).
 
 To export, publish the dataset and remove the local copy that was created after it has been uploaded:
 
-{{< configOption name="ota dataset --publish --remove-local-copy [--file <filename>]" description="Export, publish dataset and remove local copy after upload" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy`" >}}
+{{< configOption name="ota dataset --publish --remove-local-copy [--file <filename>]" description="Export, publish dataset and remove local copy after upload" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy`" />}}
 
-{{< configOption name="ota dataset --schedule [--file <filename>]" description="Schedule export, publishing and local copy removal" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy`" >}}
+{{< configOption name="ota dataset --schedule [--file <filename>]" description="Schedule export, publishing and local copy removal" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy`" />}}
 
 ## Exposing the collection API
 
-{{< configOption name="ota serve" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="`npx ota serve`" >}}
+{{< configOption name="ota serve" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="`npx ota serve`" />}}
diff --git a/content/collections/reference/configuration.md b/content/collections/reference/configuration.md
index 9ff14ca2..127ccb83 100644
--- a/content/collections/reference/configuration.md
+++ b/content/collections/reference/configuration.md
@@ -16,7 +16,7 @@ As an example, see the [production configuration file](https://github.com/OpenTe
     type="string"
     description="Defines how often the engine should check for changes in terms. Uses standard cron syntax to set the schedule."
     default="`30 */12 * * *` (runs every 12 hours at minute 30)"
->}}
+/>}}
 
 {{< configOption
     name="collectionPath"
@@ -24,7 +24,7 @@ As an example, see the [production configuration file](https://github.com/OpenTe
     description="Path to the collection's directory containing declarations directory and metadata file, relative to the engine execution location"
     example="`../collections/demo-declarations`"
     default="`./`"
->}}
+/>}}
 
 ### Recorder
 
@@ -34,13 +34,13 @@ The recorder section manages how versions and snapshots of terms are stored, sup
     name="recorder.versions.storage"
     type="object"
     description="Configuration for storing versions. Supports Git and MongoDB. See [Storage Repositories](#storage-repositories) for more information."
->}}
+/>}}
 
 {{< configOption
     name="recorder.snapshots.storage"
     type="object"
     description="Configuration for storing snapshots. Supports Git and MongoDB. See [Storage Repositories](#storage-repositories) for more information."
->}}
+/>}}
 
 ### Fetcher
 
@@ -51,21 +51,21 @@ The fetcher section configures how the engine retrieves documents from the web.
     type="number"
     description="Maximum wait time for elements to appear in a page (milliseconds)."
     default="`10000`"
->}}
+/>}}
 
 {{< configOption
     name="fetcher.navigationTimeout"
     type="number"
     description="Maximum wait time for a page to load (milliseconds)."
     default="`30000`"
->}}
+/>}}
 
 {{< configOption
     name="fetcher.language"
     type="string"
     description="Language code (ISO 639-1) for request headers."
     default="`en`"
->}}
+/>}}
 
 ### Notifier
 
@@ -76,14 +76,14 @@ The notifier section sets up how notifications are sent when new versions of ter
     type="string"
     description="SendInBlue contacts list ID of persons to notify on terms updates."
     default="`850`"
->}}
+/>}}
 
 {{< configOption
     name="notifier.sendInBlue.updateTemplateId"
     type="string"
     description="SendInBlue email template ID used for updates notifications."
     default="`7`"
->}}
+/>}}
 
 ### Logger
 
@@ -94,42 +94,42 @@ The logger section configures logging and error notification settings.
     type="string"
     description="SMTP server hostname."
     default="`smtp-relay.sendinblue.com`"
->}}
+/>}}
 
 {{< configOption
     name="logger.smtp.username"
     type="string"
     description="Username for SMTP server authentication."
     default="`admin@opentermsarchive.org`"
->}}
+/>}}
 
 {{< configOption
     name="logger.sendMailOnError.to"
     type="string"
     description="Email address for error notifications."
     example="`admin@example.com`"
->}}
+/>}}
 
 {{< configOption
     name="logger.sendMailOnError.from"
     type="string"
     description="Sender email address for error notifications."
     example="`noreply@example.com`"
->}}
+/>}}
 
 {{< configOption
     name="logger.sendMailOnError.sendWarnings"
     type="boolean"
     description="Set to true to also send email in case of warning."
     default="`false`"
->}}
+/>}}
 
 {{< configOption
     name="logger.timestampPrefix"
     type="boolean"
     description="Set to false to avoid duplicate timestamps if logs are managed by a process manager."
     default="`true`"
->}}
+/>}}
 
 ### Reporter
 
@@ -141,42 +141,42 @@ The reporter section manages how issues are reported when terms content is inacc
     description="Type of reporter"
     example="`github`"
     allowedValues="`github`, `gitlab`"
->}}
+/>}}
 
 {{< configOption
     name="reporter.repositories.declarations"
     type="string"
     description="Repository for creating issues."
     example="`OpenTermsArchive/demo-declarations`"
->}}
+/>}}
 
 {{< configOption
     name="reporter.repositories.versions"
     type="string"
     description="Repository for versions."
     example="`OpenTermsArchive/demo-versions`"
->}}
+/>}}
 
 {{< configOption
     name="reporter.repositories.snapshots"
     type="string"
     description="Repository for snapshots."
     example="`OpenTermsArchive/demo-snapshots`"
->}}
+/>}}
 
 {{< configOption
     name="reporter.baseURL"
     type="string"
     description="Base URL for GitLab (if applicable)."
     example="`https://gitlab.example.com`"
->}}
+/>}}
 
 {{< configOption
     name="reporter.apiBaseURL"
     type="string"
     description="API base URL for GitLab (if applicable)."
     example="`https://api.gitlab.example.com`"
->}}
+/>}}
 
 ### Dataset
 
@@ -187,21 +187,21 @@ The dataset section configures how datasets are published.
     type="string"
     description="Title of the dataset."
     default="`sandbox`"
->}}
+/>}}
 
 {{< configOption
     name="dataset.versionsRepositoryURL"
     type="string"
     description="Repository URL for dataset releases."
     default="`https://github.com/OpenTermsArchive/sandbox`"
->}}
+/>}}
 
 {{< configOption
     name="dataset.publishingSchedule"
     type="string"
     description="Cron expression for dataset publishing."
     default="`30 8 * * MON` (runs every Monday at 8:30 AM)"
->}}
+/>}}
 
 ### Collection API
 
@@ -213,7 +213,7 @@ The collection API section sets the parameters for the API server.
     description="Port number for the API server."
     example="`8080`"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="collection-api.api.basePath"
@@ -221,7 +221,7 @@ The collection API section sets the parameters for the API server.
     description="Base path for API endpoints."
     example="`/collection-api`"
     required=true
->}}
+/>}}
 
 ---
 
@@ -235,7 +235,7 @@ The storage repositories section set the parameters for supported backends for s
     description="Type of storage backend."
     default="`git`"
     allowedValues="`git`, `mongo`"
->}}
+/>}}
 
 ### Git
 
@@ -246,35 +246,35 @@ The Git storage configuration allows to store versions in a Git repository.
     type="string"
     description="Path to the versions database directory."
     default="`./data/versions`"
->}}
+/>}}
 
 {{< configOption
     name="storage.git.publish"
     type="boolean"
     description="Boolean to push changes to the origin."
     default="`false`"
->}}
+/>}}
 
 {{< configOption
     name="storage.git.snapshotIdentiferTemplate"
     type="string"
     description="Template for snapshot ID reference. `%SNAPSHOT_ID` will be replaced with the actual snapshot ID."
     default="`./data/snapshots/%SNAPSHOT_ID`"
->}}
+/>}}
 
 {{< configOption
     name="storage.git.author.name"
     type="string"
     description="Author name for changes."
     default="`Open Terms Archive Bot`"
->}}
+/>}}
 
 {{< configOption
     name="storage.git.author.email"
     type="string"
     description="Author email for changes."
     default="`bot@opentermsarchive.org`"
->}}
+/>}}
 
 ### MongoDB
 
@@ -285,18 +285,18 @@ The MongoDB storage configuration allows to store versions in a MongoDB database
     type="string"
     description="MongoDB connection URI."
     default="`mongodb://127.0.0.1:27017`"
->}}
+/>}}
 
 {{< configOption
     name="storage.mongo.database"
     type="string"
     description="Database name."
     default="`open-terms-archive`"
->}}
+/>}}
 
 {{< configOption
     name="storage.mongo.collection"
     type="string"
     description="Collection name."
     default="`snapshots`"
->}}
+/>}}
diff --git a/content/collections/reference/environment-variables.md b/content/collections/reference/environment-variables.md
index 16f2d415..de02430f 100644
--- a/content/collections/reference/environment-variables.md
+++ b/content/collections/reference/environment-variables.md
@@ -9,18 +9,18 @@ This reference documentation details all available environment variables that ca
 
 ### Engine
 
-{{< configOption name="OTA_ENGINE_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." >}}
+{{< configOption name="OTA_ENGINE_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." />}}
 
-{{< configOption name="OTA_ENGINE_SENDINBLUE_API_KEY" type="string" description="API key for SendInBlue." >}}
+{{< configOption name="OTA_ENGINE_SENDINBLUE_API_KEY" type="string" description="API key for SendInBlue." />}}
 
-{{< configOption name="OTA_ENGINE_GITHUB_TOKEN" type="string" description="GitHub token for API access." >}}
+{{< configOption name="OTA_ENGINE_GITHUB_TOKEN" type="string" description="GitHub token for API access." />}}
 
-{{< configOption name="OTA_ENGINE_GITLAB_TOKEN" type="string" description="GitLab token for API access." >}}
+{{< configOption name="OTA_ENGINE_GITLAB_TOKEN" type="string" description="GitLab token for API access." />}}
 
-{{< configOption name="OTA_ENGINE_GITLAB_RELEASES_TOKEN" type="string" description="GitLab token for dataset releases." >}}
+{{< configOption name="OTA_ENGINE_GITLAB_RELEASES_TOKEN" type="string" description="GitLab token for dataset releases." />}}
 
 ---
 
 ### Federation API 
 
-{{< configOption name="OTA_FEDERATION_API_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." >}}
+{{< configOption name="OTA_FEDERATION_API_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." />}}
diff --git a/content/collections/reference/metadata.md b/content/collections/reference/metadata.md
index 6daa747d..f68e96d2 100644
--- a/content/collections/reference/metadata.md
+++ b/content/collections/reference/metadata.md
@@ -19,7 +19,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="Unique identifier derived from name (acronyms, dash-separated)."
     example="demo"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="name"
@@ -27,7 +27,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="Display name of the collection."
     example="Demo Collection"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="tagline"
@@ -35,7 +35,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="Concise description of collection topic."
     example="Services used by Open Terms Archive"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="languages"
@@ -43,7 +43,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="List of [ISO 639-1 (two-letter)](https://en.wikipedia.org/wiki/ISO_639) language codes representing languages allowed in the collection."
     example="[en, fr, de]"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="jurisdictions"
@@ -51,26 +51,30 @@ The examples given throughout this reference can be seen in context in the [comp
     description="List of [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) representing jurisdictions covered by the collection."
     example="[EU]"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="description"
     type="string"
     description="Detailed description of the collection"
-    example=`    The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.
-    
-    This provides a reference collection for best practices and enables the Open Terms Archive Core Team to be a user of the software it produces.
-    `
     required=false
 >}}
 
+```yaml
+description: >
+    The **Demo** collection tracks changes to the terms of use of services used by Open Terms Archive.
+
+    This provides a reference collection for best practices and enables the Open Terms Archive Core Team to be a user of the software it produces.
+```
+{{< /configOption >}}
+
 {{< configOption
     name="dataset"
     type="uri"
     description="URL to the dataset releases."
     example="https://github.com/OpenTermsArchive/demo-versions/releases"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="declarations"
@@ -78,7 +82,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the declarations repository."
     example="https://github.com/OpenTermsArchive/demo-declarations"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="versions"
@@ -86,7 +90,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the versions repository."
     example="https://github.com/OpenTermsArchive/demo-versions"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="snapshots"
@@ -94,7 +98,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the snapshots repository."
     example="https://github.com/OpenTermsArchive/demo-snapshots"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="donations"
@@ -102,7 +106,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the donations page."
     example="https://opencollective.com/opentermsarchive"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="logo"
@@ -110,36 +114,38 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the collection's logo. Optimized PNG transparent image (minimum width 240px)."
     example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="trackingPeriods"
     type="array of objects"
     description="List of time periods during which terms were tracked, with their tracking configuration. Gaps between periods indicate times when tracking was interrupted. See [TrackingPeriods]({{< relref \"#trackingperiods\" >}}) section."
     required=false
->}}
+/>}}
 
 {{< configOption
     name="governance"
     type="object of objects"
     description="Map of organizations involved in the collection's governance, with organization names as keys and governance objects as values. See [Governance]({{< relref \"#governance\" >}}) section."
     required=false
->}}
+/>}}
 
 {{< configOption
     name="i18n"
     type="object of objects"
     description="Internationalization of any of the Metadata properties (except i18n itself) for different language codes"
-    example=`    fr:
-      name: Démo
-      tagline: Services utilisés par Open Terms Archive
-      governance:
-        Ministry for Europe and Foreign Affairs:
-          name: Ministère de l'Europe et des Affaires étrangères
-          url: https://www.diplomatie.gouv.fr
-    `
     required=false
 >}}
+```yaml
+fr:
+    name: Démo
+    tagline: Services utilisés par Open Terms Archive
+    governance:
+    Ministry for Europe and Foreign Affairs:
+        name: Ministère de l'Europe et des Affaires étrangères
+        url: https://www.diplomatie.gouv.fr
+```
+{{< /configOption >}}
 
 ---
 
@@ -151,7 +157,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="The date when tracking started for this period (ISO 8601 format YYYY-MM-DD)."
     example="2023-01-01"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="schedule"
@@ -159,7 +165,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency."
     example="0 0 * * *"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="serverLocation"
@@ -167,7 +173,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="The geographic location of the tracking server (city name and ISO 3166-2 country code)."
     example="Paris, FR"
     required=true
->}}
+/>}}
 
 {{< configOption
     name="endDate"
@@ -175,7 +181,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="The date when tracking ended for this period (ISO 8601 format YYYY-MM-DD). If not specified, tracking is ongoing."
     example="2023-12-01"
     required=false
->}}
+/>}}
 
 
 ---
@@ -188,7 +194,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the entity's website"
     example="https://opentermsarchive.org/"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="logo"
@@ -196,7 +202,7 @@ The examples given throughout this reference can be seen in context in the [comp
     description="URL to the entity's logo. Optimized PNG transparent image (minimum width 240px)."
     example="https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png"
     required=false
->}}
+/>}}
 
 {{< configOption
     name="roles"
@@ -205,4 +211,4 @@ The examples given throughout this reference can be seen in context in the [comp
     allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`"
     example="[host, administrator]"
     required=true
->}}
+/>}}
diff --git a/themes/opentermsarchive/assets/css/components/configOption.css b/themes/opentermsarchive/assets/css/components/configOption.css
index a0276f9b..a158d06c 100644
--- a/themes/opentermsarchive/assets/css/components/configOption.css
+++ b/themes/opentermsarchive/assets/css/components/configOption.css
@@ -6,8 +6,10 @@
   box-shadow: inset 0 1px var(--colorBlack200);
 }
 
-.config-option .config-option-name code {
+.config-option-name code {
   font-weight: 600;
+  overflow-y: auto;
+  font-size: 1em;
 }
 
 .config-option-type {
@@ -18,14 +20,21 @@
 
 .config-option-required {
   padding-left: 1rem;
-  text-transform: lowercase;
   color: rgb(154, 103, 0);
 }
 
+.config-option-required code {
+  font-weight: 400;
+}
+
 .config-option-details {
   display: flex;
 }
 
+.config-option-details__full {
+  flex-direction: column;
+}
+
 .config-option-description,
 .config-option-default,
 .config-option-example,
@@ -35,7 +44,7 @@
 
 .config-option-example code,
 .config-option-default code,
-.config-option-allowed-values code {
+.config-option-allowed-values-list {
   margin-left: 0.4em;
   display: inline-block;
 }
@@ -45,3 +54,12 @@
 .config-option-allowed-values {
   font-size: 0.85em;
 }
+
+.config-option-details_full .config-option-example {
+  overflow-y: auto;
+  width: 100%;
+}
+
+.config-option-details_full .config-option-example .highlight {
+  margin-top: 0.4em;
+}
diff --git a/themes/opentermsarchive/layouts/shortcodes/configOption.html b/themes/opentermsarchive/layouts/shortcodes/configOption.html
index 99b48f03..3d47810b 100644
--- a/themes/opentermsarchive/layouts/shortcodes/configOption.html
+++ b/themes/opentermsarchive/layouts/shortcodes/configOption.html
@@ -1,28 +1,39 @@
+{{ $name := .Get "name" }}
+{{ $type := .Get "type" }}
+{{ $required := .Get "required" }}
+{{ $allowedValues := .Get "allowedValues" }}
+{{ $default := .Get "default" }}
+{{/* Get description either from attribute or nested content */}}
+{{ $description := .Get "description" }}
+{{ $example := .Get "example" }}
+
 <div class="config-option">
     <div class="config-option-name">
-        <code>{{ .Get "name" }}</code>
-        <span class="config-option-type">{{ .Get "type" }}</span>
-        {{ if .Get "required" }}
-        <span class="config-option-required">Required</span>
+        <code>{{ $name }}</code>
+        <span class="config-option-type">{{ $type }}</span>
+        {{ with $required }}
+            <span class="config-option-required">{{ if eq . true }}required{{ else }}{{ . | markdownify }}{{ end }}</span>
         {{ end }}
     </div>
-    <div class="config-option-description">{{ .Get "description" | markdownify }}</div>
-    <div class="config-option-details">
-        {{ if .Get "default" }}
-        <div class="config-option-default"><span>Default:</span>{{ .Get "default" | markdownify}}</div>
+    <div class="config-option-description">
+        {{ $description | markdownify | safeHTML }}
+    </div>
+    <div class="config-option-details config-option-details__{{ if .Inner }}full{{ end }}">
+        {{ if $default }}
+        <div class="config-option-default"><span>Default:</span>{{ $default | markdownify}}</div>
         {{ end }}
-        {{ if .Get "example" }}
+        {{ if or $example .Inner }}
         <div class="config-option-example"><span>Example:</span>
-            {{ $example := .Get "example" }}
-            {{ if not (strings.Contains $example "\n") }}
-                <code>{{ $example | markdownify }}</code>
+            {{ if .Inner }}
+                {{ .Inner | markdownify }}
             {{ else }}
-                {{ $example | markdownify }}
+                <code>{{ $example | markdownify }}</code>
             {{ end }}
         </div>
         {{ end }}
-        {{ if .Get "allowedValues" }}
-        <div class="config-option-allowed-values"><span>Allowed values:</span>{{ .Get "allowedValues" | markdownify }}</div>
+        {{ if $allowedValues }}
+        <div class="config-option-allowed-values"><span>Allowed values:</span><span class="config-option-allowed-values-list">{{ $allowedValues | markdownify }}</span></div>
         {{ end }}
     </div>
 </div>
+

From e98ca891ceff624ef0554d77e06728cf2cc1f1c2 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Thu, 27 Mar 2025 10:48:09 +0100
Subject: [PATCH 02/20] Add service declaration reference

---
 content/terms/reference/declaration.md | 495 +++++++++----------------
 1 file changed, 179 insertions(+), 316 deletions(-)

diff --git a/content/terms/reference/declaration.md b/content/terms/reference/declaration.md
index cc98caa3..c29077c8 100644
--- a/content/terms/reference/declaration.md
+++ b/content/terms/reference/declaration.md
@@ -1,355 +1,218 @@
 ---
-title: "Declaration format"
+title: "Service declaration"
 aliases: "/terms/reference/"
 ---
 
-# Terms declaration format reference
+# Service declaration
 
-Terms are declared in a service declaration file, under the `terms` property.
+This reference documentation details all available properties that can be specified in a service's declaration file.
 
-Most of the time, terms are written in only one source document (for example [Facebook Terms of Service](https://www.facebook.com/legal/terms)) but sometimes terms can be spread across multiple online source documents, and their combination constitutes the terms (for example [Facebook Community Guidelines](https://transparency.fb.com/policies/community-standards/)).
+The examples given throughout this reference can be seen in context in the [declarations files](https://github.com/OpenTermsArchive/demo-declarations/tree/main/declarations) from the [Demo collection](https://github.com/OpenTermsArchive/demo-declarations)
 
-## Source document
+## Properties
 
-The way in which a source document is obtained is defined in a JSON object:
+{{< configOption
+    name="name"
+    type="string"
+    description="The name of the service."
+    example="Open Terms Archive"
+    required=true
+/>}}
 
-```json
-{
-  "fetch": "The URL where the document can be found",
-  "executeClientScripts": "A boolean to execute client-side JavaScript loaded by the document before accessing the content, in case the DOM modifications are needed to access the content; defaults to false (fetch HTML only)",
-  "filter": "An array of service specific filter function names",
-  "remove": "A CSS selector, a range selector or an array of selectors that target the insignificant parts of the document that has to be removed. Useful to remove parts that are inside the selected parts",
-  "select": "A CSS selector, a range selector or an array of selectors that target the meaningful parts of the document, excluding elements such as headers, footers and navigation"
-}
-```
-
-- For HTML files, `fetch` and `select` are mandatory.
-- For PDF files, only `fetch` is mandatory.
-
-Let’s start by defining these keys!
-
-## `fetch`
-
-This property should simply contain the URL at which the terms you want to track can be downloaded. HTML and PDF files are supported.
-
-When terms coexist in different languages and jurisdictions, please refer to the [scope of the collection]({{< relref "collections/reference/metadata" >}}) to which you are contributing. This scope is usually defined in the README.
-
-## `select`
-
-_This property is not needed for PDF documents._
-
-Most of the time, contractual documents are exposed as web pages, with a header, a footer, navigation menus, possibly ads… We aim at tracking only the significant parts of the document. In order to achieve that, the `select` property allows to extract only those parts in the process of [converting from snapshot to version](https://opentermsarchive.org/#how-it-works).
-
-The `select` value can be either a [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors), a [range selector](#range-selectors) or an array of those.
-
-### CSS selectors
+{{< configOption
+    name="terms"
+    type="object of objects"
+    description=`Map of terms associated with a service, where keys are standardized term types (e.g., "Privacy Policy", "Terms of Service"), and values are term objects containing the configuration for fetching and processing each document, as detailed in the [Terms declaration]({{< relref \"#terms-declaration\" >}}) section.
 
-CSS selectors should be provided as a string. See the [specification](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) for how to write CSS selectors.
-
-> For example, the following selector will select the content in the `<main>` tag of the HTML document:
->
-> ```json
-> "select": "main"
-> ```
-
-### Range selectors
-
-A range selector is defined with a _start_ and an _end_ CSS selector. It is also necessary to define if the range starts before or after the element targeted by the _start_ CSS selector and to define if it ends before or after the element targeted by the _end_ CSS selector.
-
-To that end, a range selector is a JSON object containing two keys out of the four that are available: `startBefore`, `startAfter`, `endBefore` and `endAfter`.
+To facilitate cross-service comparisons and ensure consistency, a standardized list of term types is maintained in a [dedicated repository](https://github.com/OpenTermsArchive/terms-types).
 
+Please note, the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”.
+    `
+    required=true
+    allowedValues="See the [terms-types repository](https://github.com/OpenTermsArchive/terms-types)."
+>}}
 ```json
-{
-  "start[Before|After]": "<CSS selector>",
-  "end[Before|After]": "<CSS selector>"
+"terms": {
+    "Terms of Service": {
+      "fetch": "https://opencollective.com/tos",
+      "select": ".markdown"
+    },
+    "Privacy Policy": {
+      "fetch": "https://opencollective.com/privacypolicy",
+      "select": ".markdown"
+    }
 }
 ```
+{{< /configOption >}}
 
-> For example, the following selector will select the content between the element targeted by the CSS selector `#privacy-eea`, including it, and the element targeted by the CSS selector `footer`, excluding it:
->
-> ```json
-> {
->   "startBefore": "#privacy-eea",
->   "endBefore": "footer"
-> }
-> ```
-
-## `remove`
-
-_This property is optional._
-
-Beyond [selecting a subset of a web page](#select), some documents will have non-significant parts in the middle of otherwise significant parts. For example, they can have “go to top” links or banner ads. These can be removed by listing [CSS selectors](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors), [range selectors](#range-selectors) or an array of them under the `remove` property.
-
-### Example
-
-Let's assume a web page contains the following content:
-
-```html
-<main>
-  <div class="filter-holder">
-    <select class="filter-options">
-        <option value="https://www.example.com/policies/user-agreement" selected>User Agreement</option>
-        <option value="https://www.example.com/policies/privacy-policy">Privacy Policy</option>
-        <option value="https://www.example.com/policies/content-policy">Content Policy</option>
-        <option value="https://www.example.com/policies/broadcasting-content-policy">Broadcasting Content Policy</option>
-    </select>
-  </div>
-  <h1>User Agreement</h1>
-  <div>…terms…</div>
-</main>
-```
-
-If only `main` is used in `select`, the following version will be extracted:
-
-```md
-User Agreement Privacy Policy Content Policy Broadcasting Content Policy Moderator Guidelines Transparency Report 2017 Transparency Report 2018 Guidelines for Law Enforcement Transparency Report 2019
-
-User Agreement
-==============
-
-…terms…
-```
-
-Whereas we want instead:
-
-```md
-User Agreement
-==============
-
-…terms…
-```
-
-This result can be obtained with the following declaration:
+---
 
+### Terms declaration
+
+{{< configOption
+    name="fetch"
+    type="uri"
+    description="The URL where the terms document can be downloaded."
+    example="https://opentermsarchive.org/en/privacy-policy"
+    required=true
+/>}}
+
+{{< configOption
+    name="select"
+    type="string, object or array"
+    description=`
+The way to select the parts of the document to extract. Can be:
+
+- a CSS selector string. See the [CSS Selectors specification](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)
+- a range selector object. See the [range selector]({{< relref \"#range-selector\" >}}) section
+- an array of those`
+    required="required for HTML documents"
+>}}
+As a direct CSS selector:
 ```json
-{
-  "fetch": "https://example.com/user-agreement",
-  "select": "main",
-  "remove": ".filter-holder"
-}
+"select": "#article-contents"
 ```
 
-### Complex selectors examples
-
+As a range selector object:
 ```json
-{
- "fetch": "https://support.google.com/adsense/answer/48182",
- "select": ".article-container",
- "remove": ".print-button, .go-to-top"
+"select": {
+    "startBefore": "h1",
+    "endBefore": "#toc-heading"
 }
 ```
 
+As an array of those:
 ```json
-{
- "fetch": "https://www.wechat.com/en/service_terms.html",
- "select": "#agreement",
- "remove": {
-   "startBefore": "#wechat-terms-of-service-usa-specific-terms-",
-   "endBefore": "#wechat-terms-of-service-european-union-specific-terms-"
- }
-}
-```
-
+"select": [
+    "#article-contents",
+    {
+        "startBefore": "h1",
+        "endBefore": "#toc-heading"
+    }
+]
+```
+{{< /configOption >}}
+
+{{< configOption
+    name="executeClientScripts"
+    type="boolean"
+    description=`Boolean flag to execute client-side JavaScript before accessing content.
+
+When enabled, this loads the page in a headless browser to execute client-side scripts and load dynamic content, which is necessary when JavaScript modifies or loads content after the initial page load.`
+    default=false
+    example="true"
+/>}}
+
+{{< configOption
+    name="remove"
+    type="string, object or array"
+    description=`
+The way to remove the parts of the document that are not part of the terms and can be considered as noise. Can be:
+
+- a CSS selector string. See the [CSS Selectors specification](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors)
+- a range selector object. See the [range selector]({{< relref \"#range-selector\" >}}) section
+- an array of those`
+>}}
+As a direct CSS selector:
 ```json
-{
- "fetch": "https://fr-fr.facebook.com/legal/terms/plain_text_terms",
- "select": "div[role=main]",
- "remove": [
-   {
-     "startBefore": "[role=\"separator\"]",
-     "endAfter": "body"
-   },
-   "[style=\"display:none\"]"
- ]
-}
-```
-
-## `executeClientScripts`
-
-_This property is optional._
-
-In some cases, the content of the document is only loaded (or is modified dynamically) by client scripts.
-When set to `true`, this boolean property loads the page in a headless browser to load all assets and execute client scripts before trying to get the document contents.
-
-Since the performance cost of this approach is high, it is set to `false` by default, relying on the HTML content only.
-
-## `filter`
-
-_This property is optional._
-
-Finally, some documents will need more complex filtering beyond simple element selection and removal, for example to remove noise (changes in textual content that are not meaningful to the terms of services). Such filters are declared as JavaScript functions that modify the downloaded web page through the [DOM API](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model).
-
-Filters take the document DOM and the terms declaration as parameters and are:
-
-- **in-place**: they modify the document structure and content directly;
-- **idempotent**: they should return the same document structure and content even if run repeatedly on their own result.
-
-Filters are loaded automatically from files named after the service they operate on. For example, filters for the Meetup service, which is declared in `declarations/Meetup.json`, are loaded from `declarations/Meetup.filters.js`.
-
-The generic function signature for a filter is:
-
-```js
-export [async] function filterName(document, documentDeclaration)
-```
-
-Each filter is exposed as a named function export that takes a `document` parameter and behaves like the `document` object in a browser DOM. These functions can be `async`, but they will still run sequentially. The whole document declaration is passed as second parameter.
-
-> The `document` parameter is actually a [JSDOM](https://github.com/jsdom/jsdom) document instance.
-
-You can learn more about usual noise and ways to handle it [in the guidelines]({{< relref "/terms/guidelines/declaring#usual-noise" >}}).
-
-### Example
-
-Let's assume a service adds a unique `clickId` parameter in the query string of all link destinations. These parameters change on each page load, leading to recording noise in versions. Since links should still be recorded, it is not appropriate to use `remove` to remove the links entirely. Instead, a filter will manipulate the links destinations to remove the always-changing parameter. Concretely, the goal is to apply the following filter:
-
-```diff
-- Read the <a href="https://example.com/example-page?clickId=349A2033B&lang=en">list of our affiliates</a>.
-+ Read the <a href="https://example.com/example-page?lang=en">list of our affiliates</a>.
+"remove": ".nav, .breadcrumb"
 ```
 
-The code below implements this filter:
-
-```js
-function removeTrackingIdsQueryParam(document) {
-  const QUERY_PARAM_TO_REMOVE = 'clickId';
-
-  document.querySelectorAll('a').forEach(link => {  // iterate over every link in the page
-    const url = new URL(link.getAttribute('href'), document.location);  // URL is part of the DOM API, see https://developer.mozilla.org/en-US/docs/Web/API/URL
-    const params = new URLSearchParams(url.search);  // URLSearchParams is part of the DOM API, see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
-
-    params.delete(QUERY_PARAM_TO_REMOVE);  // we use the DOM API instead of RegExp because we can't know in advance in which order parameters will be written
-    url.search = params.toString();  // store the query string without the parameter
-    link.setAttribute('href', url.toString());  // write the destination URL without the parameter
-  });
-}
-```
-
-### Example usage of declaration parameter
-
-The second parameter can be used to access the defined document URL or selector inside the filter.
-
-Let's assume a service stores some of its legally-binding terms in images. To track these changes properly, images should be stored as part of the terms. By default, images are not stored since they significantly increase the document size. The filter below will store images inline in the terms, encoded in a [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URLs). In order to download the images for conversion, the base URL of the web page is needed to resolve relative links. This information is obtained from the declaration.
-
-```js
-import fetch from 'isomorphic-fetch';
-
-export async function convertImagesToBase64(document, documentDeclaration) {
-  const { fetch: baseUrl, select: selector } = documentDeclaration;
-  
-  const images = Array.from(document.querySelectorAll(`${selector} img`));
-
-  return Promise.all(images.map(async ({ src }, index) => {
-    const imageAbsoluteUrl = new URL(src, baseUrl).href;
-    const response = await fetch(imageAbsoluteUrl);
-    const mimeType = response.headers.get('content-type');
-    const content = await response.arrayBuffer();
-
-    const base64Image = btoa(String.fromCharCode(...new Uint8Array(content)));
-
-    images[index].src = `data:${mimeType};base64,${base64Image}`;
-  }));
+As a range selector object:
+```json
+"remove": {
+    "startBefore": ".nav",
+    "endBefore": ".breadcrumb"
 }
 ```
 
-## Terms with a single source document
-
-In the case where terms are extracted from one single source document, they are declared by simply declaring that source document:
-
+As an array of those:
 ```json
-  …
-  "terms": {
-    "<terms type>": {
-      "fetch": "…",
-      "executeClientScripts": "…",
-      "filter": "…",
-      "remove": "…",
-      "select": "…"
+"remove": [
+    ".nav, .breadcrumb",
+    {
+        "startBefore": "#contact-us",
+        "endBefore": "#footer"
     }
-  }
-  …
-```
-
-## Terms with multiple source documents
-
-When the terms are spread across multiple source documents, they should be declared by declaring their combination:
-
+]
+```
+{{< /configOption >}}
+
+{{< configOption
+    name="filter"
+    type="array of strings"
+    description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"/terms/explanation/filters\" >}}) section for more information."
+    example="[\"filterName1\", \"filterName2\"]"
+/>}}
+
+{{< configOption
+    name="combine"
+    type="array of objects"
+    description=`
+An array of terms declaration objects that will be combined into a single terms document. Each object in the array can contain all the same properties as a regular terms  declaration (except "combine").
+
+Common properties (can be a combination of "select", "remove", "filter" and "executeClientScripts") that are shared across all source documents can be factorized by declaring them at the root level of the terms declaration.
+    `
+>}}
 ```json
-  …
-  "terms": {
-    "<terms type>": {
-        "combine": [
-        {
-          "fetch": "…",
-          "executeClientScripts": "…",
-          "filter": "…",
-          "remove": "…",
-          "select": "…"
-        },
-        {
-          "fetch": "…",
-          "executeClientScripts": "…",
-          "filter": "…",
-          "remove": "…",
-          "select": "…"
-        }
-      ]
+"combine": [
+    {
+        "fetch": "https://example.com/terms/part1",
+        "select": "#main-content",
+        "remove": ".ads"
+    },
+    {
+        "fetch": "https://example.com/terms/part2",
+        "select": "#main-content",
+        "remove": ".ads"
     }
-  }
-  …
-```
-
-If some parts of the source documents are repeated, they can be factorised. For example, it is common for the structure of HTML pages to be similar from page to page, so `select`, `remove` and `filter` would be the same. These elements can be shared instead of being duplicated:
-
-```json
-  …
-  "terms": {
-    "<terms type>": 
-      "executeClientScripts": "…",
-      "filter": "…",
-      "remove": "…",
-      "select": "…",
-      "combine": [
-        {
-          "fetch": "…",
-        },
-        {
-          "fetch": "…",
-        }
-      ]
-  }
-  …
-```
-
-## Terms type
-
-Great, your terms declaration is now almost complete! You simply need to write it under the appropriate terms type in the `terms` JSON object within the service declaration.
-
-In order to distinguish between the many terms that can be associated with a service and enable cross-services comparison of similar terms, we maintain a unique list of terms types in a [dedicated repository](https://github.com/OpenTermsArchive/terms-types).
-
-Please note, the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”.
-
-If the terms you want to add don't match an existing type, you can [suggest a new one](https://github.com/OpenTermsArchive/terms-types/blob/main/CONTRIBUTING.md).
-
-## Testing your declaration
-
-You can test the declarations you created or changed by running the following command:
-
-```sh
-npm test [$service_id [$another_service_id …]]
+]
 ```
+{{< /configOption >}}
 
-Since this operation fetches documents and could be long, you can also validate the declaration structure only:
-
-```sh
-npm run test:schema [$service_id [$another_service_id …]]
-```
-
-## Linting
-
-In order to ensure consistency across declarations, all declarations files have to be formatted homogeneously.
+---
 
-In order to achieve this, you can use the following command:
+### Range selector
+
+{{< configOption
+    name="startBefore"
+    type="CSS selector"
+    description="The CSS selector for the element before which the range starts."
+    example="#privacy-eea"
+    required="either `startBefore` or `startAfter` is required"
+/>}}
+
+{{< configOption
+    name="startAfter"
+    type="CSS selector"
+    description="The CSS selector for the element after which the range starts."
+    example="#privacy-eea"
+    required="either `startBefore` or `startAfter` is required"
+/>}}
+
+{{< configOption
+    name="endBefore"
+    type="CSS selector"
+    description="The CSS selector for the element before which the range ends."
+    example="footer"
+    required="either `endBefore` or `endAfter` is required"
+/>}}
+
+{{< configOption
+    name="endAfter"
+    type="CSS selector"
+    description="The CSS selector for the element after which the range ends."
+    example="footer"
+    required="either `endBefore` or `endAfter` is required"
+/>}}
+
+#### Example
+
+To capture content starting from and including a privacy section up until but excluding the footer:
 
-```sh
-npm run lint [$service_id [$another_service_id …]]
+```json
+{
+  "startBefore": "#privacy-section",
+  "endBefore": "footer"
+}
 ```

From 8695ab3c886579bf90f2a19adb01a6ae36f05fed Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Mon, 31 Mar 2025 09:18:37 +0200
Subject: [PATCH 03/20] Add How to test your declarations

---
 content/terms/how-to/test-declaration.md | 58 ++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 content/terms/how-to/test-declaration.md

diff --git a/content/terms/how-to/test-declaration.md b/content/terms/how-to/test-declaration.md
new file mode 100644
index 00000000..5014ee18
--- /dev/null
+++ b/content/terms/how-to/test-declaration.md
@@ -0,0 +1,58 @@
+---
+title: "Test your declarations"
+weight: 4
+---
+
+# Test your declarations
+
+When creating or modifying service declarations, it's important to verify they work as expected. Let's see how to test your declarations in different ways.
+
+## Full testing
+
+To test your declarations by actually fetching the documents and validating the entire process:
+
+```sh
+npx ota validate declarations
+```
+
+It is also possible to test a single service declaration:
+
+```sh
+npx ota validate declarations --services "<service-name>"
+```
+
+Even a single terms of a service can be tested:
+
+```sh
+npx ota validate declarations --services "<service-name>" --terms "<terms-type>"
+```
+
+## Schema validation only
+
+For quicker validation that only checks the declaration structure without fetching any documents:
+
+```sh
+npx ota validate declarations --schema-only
+```
+
+This is useful during initial development to ensure your JSON structure is correct before testing the actual document fetching.
+
+Same options as for the full test are available.
+
+## Linting declarations
+
+To ensure consistency across all declarations, you should also run the linter:
+
+```sh
+npx ota lint
+```
+
+Same options as for the full test are available.
+
+To automatically fix linting errors:
+
+```sh
+npx ota lint --fix
+```
+
+This will format your declaration files according to the project's standards.

From 771951b274e788f065ba3fab88d4b4c00f883a23 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Mon, 31 Mar 2025 10:01:29 +0200
Subject: [PATCH 04/20] Add range selector explanation

---
 content/terms/explanation/range-selectors.md | 86 ++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 content/terms/explanation/range-selectors.md

diff --git a/content/terms/explanation/range-selectors.md b/content/terms/explanation/range-selectors.md
new file mode 100644
index 00000000..98362280
--- /dev/null
+++ b/content/terms/explanation/range-selectors.md
@@ -0,0 +1,86 @@
+---
+title: Range selectors
+---
+
+## Range selectors
+
+Content between two elements in a document can be selected using a range selector, regardless of their DOM position. When no unique wrapper element exists for the whole terms content and their is no easy way to select the content with only CSS selectors, range selectors can be utilized. The concept is inspired by the [Range API](https://developer.mozilla.org/en-US/docs/Web/API/Range), where content is defined by start and end points that may be inclusive or exclusive. The format is defined as a JSON object in the following way:
+
+```json
+{
+  "start[Before|After]": "CSS selector that marks where to begin capturing content",
+  "end[Before|After]": "CSS selector that marks where to stop capturing content"
+}
+```
+
+### Example
+
+Let's take an example to see when range selectors can be useful. Given the following HTML:
+
+```html
+<html>
+
+<body>
+  <main>
+    <!-- Breadcrumb Navigation -->
+    <div>
+      <ol>
+        <li><a href="/">Home</a></li>
+        <li><a href="/legal">Legal</a></li>
+        <li>Terms and Conditions</li>
+      </ol>
+    </div>
+
+    <!-- Sub Navigation -->
+    <div>
+      <nav>
+        <ul>
+          <li>
+            <a href="/legal/terms">Terms and Conditions</a>
+          </li>
+          <li>
+            <a href="/legal/privacy">Privacy Policy</a>
+          </li>
+        </ul>
+      </nav>
+    </div>
+
+    <!-- Main Content -->
+    <h1><a id="terms-title" href="#terms-title">Example Terms</a></h1>
+    <p>Effective as of: January 1, 2024</p>
+
+    <h2><a id="section-1" href="#section-1">1. Introduction</a></h2>
+    <p>These are example terms and conditions.</p>
+
+    <h2><a id="section-2" href="#section-2">2. Usage</a></h2>
+    <p>Sample usage guidelines go here.</p>
+  </main>
+
+
+  <footer id="page-footer">
+    <nav>
+      <div>
+        <ul>
+          <li><a href="/about">About</a></li>
+          <li><a href="/contact">Contact</a></li>
+        </ul>
+      </div>
+    </nav>
+  </footer>
+</body>
+
+</html>
+```
+
+In this case, there is no unique wrapper element for the terms content which is represented by all elements after the main title in the `main` element. Here selecting the whole `main` would result in selecting elements that are not part of the terms content, like the breadcrumb and sub navigation. The range selector can be used to select the terms content by specifying the main title `#terms-title` as the start point and the footer `#page-footer` as the end point. The selection starts *before* the main title, so it includes it, and ends *before* the footer, so it excludes it.
+
+So the resulting range selector is:
+
+```json
+{
+  "startBefore": "#terms-title",
+  "endBefore": "#page-footer"
+}
+```
+
+This range selector will select the terms content between the main title and the footer element.

From d486b214e18cc1beaac07b4ef3c3c8710c713d44 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Mon, 31 Mar 2025 10:32:21 +0200
Subject: [PATCH 05/20] Add filters explanation

---
 content/terms/explanation/_index.md  |  4 +++
 content/terms/explanation/filters.md | 54 ++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 content/terms/explanation/_index.md
 create mode 100644 content/terms/explanation/filters.md

diff --git a/content/terms/explanation/_index.md b/content/terms/explanation/_index.md
new file mode 100644
index 00000000..82b01122
--- /dev/null
+++ b/content/terms/explanation/_index.md
@@ -0,0 +1,4 @@
+---
+title: Explanation
+weight: 2
+---
diff --git a/content/terms/explanation/filters.md b/content/terms/explanation/filters.md
new file mode 100644
index 00000000..0f2d23cd
--- /dev/null
+++ b/content/terms/explanation/filters.md
@@ -0,0 +1,54 @@
+---
+title: "Filters"
+---
+
+# Filters
+
+Some documents require more complex filtering beyond basic element selection and removal. For example, web pages often contain dynamically generated content like tracking IDs in URLs that change on each page load. While these elements are part of the page, they are not meaningful to the terms content itself. If such dynamic content is included in the archived versions, it creates a lot of insignificant versions and pollutes the archive with noise that makes it harder to identify actual changes to the terms.
+
+Filters address this need by providing a way to programmatically clean up and normalize the content before archiving. They are implemented as JavaScript functions that can manipulate the downloaded web page using the [DOM API](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model), allowing for sophisticated content transformations beyond what's possible with simple CSS selectors.
+
+Filters take the document DOM and the terms declaration as parameters and are:
+
+- **in-place**: they modify the document structure and content directly;
+- **idempotent**: they should return the same document structure and content even if run repeatedly on their own result.
+
+Filters are loaded automatically from files named after the service they operate on. For example, filters for the Meetup service, which is declared in `declarations/Meetup.json`, are loaded from `declarations/Meetup.filters.js`.
+
+The generic function signature for a filter is:
+
+```js
+export [async] function filterName(document, documentDeclaration)
+```
+
+Each filter is exposed as a named function export that takes a `document` parameter and behaves like the `document` object in a browser DOM. These functions can be `async`, but they will still run sequentially. The whole document declaration is passed as second parameter.
+
+> The `document` parameter is actually a [JSDOM](https://github.com/jsdom/jsdom) document instance.
+
+You can learn more about usual noise and ways to handle it [in the guidelines]({{< relref "/terms/guidelines/declaring#usual-noise" >}}).
+
+### Example
+
+Let's assume a service adds a unique `clickId` parameter in the query string of all link destinations. These parameters change on each page load, leading to recording noise in versions. Since links should still be recorded, it is not appropriate to use `remove` to remove the links entirely. Instead, a filter will manipulate the links destinations to remove the always-changing parameter. Concretely, the goal is to apply the following filter:
+
+```diff
+- Read the <a href="https://example.com/example-page?clickId=349A2033B&lang=en">list of our affiliates</a>.
++ Read the <a href="https://example.com/example-page?lang=en">list of our affiliates</a>.
+```
+
+The code below implements this filter:
+
+```js
+function removeTrackingIdsQueryParam(document) {
+  const QUERY_PARAM_TO_REMOVE = 'clickId';
+
+  document.querySelectorAll('a').forEach(link => {  // iterate over every link in the page
+    const url = new URL(link.getAttribute('href'), document.location);  // URL is part of the DOM API, see https://developer.mozilla.org/en-US/docs/Web/API/URL
+    const params = new URLSearchParams(url.search);  // URLSearchParams is part of the DOM API, see https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams
+
+    params.delete(QUERY_PARAM_TO_REMOVE);  // we use the DOM API instead of RegExp because we can't know in advance in which order parameters will be written
+    url.search = params.toString();  // store the query string without the parameter
+    link.setAttribute('href', url.toString());  // write the destination URL without the parameter
+  });
+}
+```

From e3fddeb0b33c43703af455800f8111a4b71a9a75 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Mon, 31 Mar 2025 10:39:49 +0200
Subject: [PATCH 06/20] Move uncategorised doc

---
 content/terms/{ => explanation}/declarations-maintenance.md | 2 ++
 content/terms/guidelines/reviewing.md                       | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)
 rename content/terms/{ => explanation}/declarations-maintenance.md (98%)

diff --git a/content/terms/declarations-maintenance.md b/content/terms/explanation/declarations-maintenance.md
similarity index 98%
rename from content/terms/declarations-maintenance.md
rename to content/terms/explanation/declarations-maintenance.md
index c36c22f0..b572df81 100644
--- a/content/terms/declarations-maintenance.md
+++ b/content/terms/explanation/declarations-maintenance.md
@@ -1,6 +1,8 @@
 ---
 title: "Declarations maintenance"
 weight: 6
+aliases:
+  - /terms/declarations-maintenance/
 ---
 
 # Declarations maintenance
diff --git a/content/terms/guidelines/reviewing.md b/content/terms/guidelines/reviewing.md
index 1f58e455..0354592e 100644
--- a/content/terms/guidelines/reviewing.md
+++ b/content/terms/guidelines/reviewing.md
@@ -72,7 +72,7 @@ The pull request created will consist of fewer checks than those that add declar
 
 For pull requests that update declarations, you should focus should be on two things: history file and declaration.
 
-- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/declarations-maintenance" >}}).
+- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/explanation/declarations-maintenance" >}}).
 - **Declaration:** for `update` pull requests, you only look at the selectors to make sure they are **simple** and also verify the **generated version** is ok.
 
 ### Step-by-step Review Guide
@@ -84,7 +84,7 @@ For pull requests that update declarations, you should focus should be on two th
 5. Compare it with the `validUntil` property in the history file under the `Files changes` section of the pull request. If the dates are the same, proceed to approve the pull request.
 6. Merge the contribution.
 
-You can read more about maintaining declarations from the [official documentation]({{< relref "terms/declarations-maintenance" >}}).
+You can read more about maintaining declarations from the [official documentation]({{< relref "terms/explanation/declarations-maintenance" >}}).
 
 ## When to Make Changes to a Contribution
 

From 93fac44af3752a64e5d5b65e1a467defa0000fce Mon Sep 17 00:00:00 2001
From: Matti Schneider <matti@opentermsarchive.org>
Date: Tue, 1 Apr 2025 18:06:23 +0200
Subject: [PATCH 07/20] Improve Test your declarations page

---
 content/terms/how-to/test-declaration.md | 31 +++++++++---------------
 1 file changed, 11 insertions(+), 20 deletions(-)

diff --git a/content/terms/how-to/test-declaration.md b/content/terms/how-to/test-declaration.md
index 5014ee18..22589203 100644
--- a/content/terms/how-to/test-declaration.md
+++ b/content/terms/how-to/test-declaration.md
@@ -5,54 +5,45 @@ weight: 4
 
 # Test your declarations
 
-When creating or modifying service declarations, it's important to verify they work as expected. Let's see how to test your declarations in different ways.
+When creating or modifying service declarations, it’s important to verify they work as expected before starting to track in production. The Open Terms Archive engine provides automated testing tools to that end.
 
-## Full testing
-
-To test your declarations by actually fetching the documents and validating the entire process:
+The basic usage to test all declarations in a collection is:
 
 ```sh
 npx ota validate declarations
 ```
 
-It is also possible to test a single service declaration:
-
-```sh
-npx ota validate declarations --services "<service-name>"
-```
+## Testing specific services
 
-Even a single terms of a service can be tested:
+When iterating over a specific declaration, or to narrow down testing in larger collections, the `--services` and `--terms` options enable testing a single service declaration, or even single terms:
 
 ```sh
+npx ota validate declarations --services "<service-name>"
 npx ota validate declarations --services "<service-name>" --terms "<terms-type>"
 ```
 
 ## Schema validation only
 
-For quicker validation that only checks the declaration structure without fetching any documents:
+During initial development, it is useful to check that the JSON structure is correct before even testing the actual document fetching. The `--schema-only` option enables faster validation by only checking the declaration structure without fetching any documents:
 
 ```sh
 npx ota validate declarations --schema-only
 ```
 
-This is useful during initial development to ensure your JSON structure is correct before testing the actual document fetching.
+The same options for targeting specific services and terms are available.
 
-Same options as for the full test are available.
+## Formatting
 
-## Linting declarations
-
-To ensure consistency across all declarations, you should also run the linter:
+To ensure formatting consistency across all declarations, a linter is provided:
 
 ```sh
 npx ota lint
 ```
 
-Same options as for the full test are available.
-
-To automatically fix linting errors:
+To automatically apply the default Open Terms Archive formatting options:
 
 ```sh
 npx ota lint --fix
 ```
 
-This will format your declaration files according to the project's standards.
+The same options for targeting specific services and terms are available.

From 4bafcacb6258e6f332aa111cbf2f70f283b33816 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 2 Apr 2025 10:28:22 +0200
Subject: [PATCH 08/20] Improve wording

Co-authored-by: Matti Schneider <matti@opentermsarchive.org>
---
 content/terms/explanation/filters.md         | 2 +-
 content/terms/explanation/range-selectors.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/terms/explanation/filters.md b/content/terms/explanation/filters.md
index 0f2d23cd..3a638065 100644
--- a/content/terms/explanation/filters.md
+++ b/content/terms/explanation/filters.md
@@ -11,7 +11,7 @@ Filters address this need by providing a way to programmatically clean up and no
 Filters take the document DOM and the terms declaration as parameters and are:
 
 - **in-place**: they modify the document structure and content directly;
-- **idempotent**: they should return the same document structure and content even if run repeatedly on their own result.
+- **idempotent**: they return the same document structure and content even if run repeatedly on their own result.
 
 Filters are loaded automatically from files named after the service they operate on. For example, filters for the Meetup service, which is declared in `declarations/Meetup.json`, are loaded from `declarations/Meetup.filters.js`.
 
diff --git a/content/terms/explanation/range-selectors.md b/content/terms/explanation/range-selectors.md
index 98362280..9b9a9d6d 100644
--- a/content/terms/explanation/range-selectors.md
+++ b/content/terms/explanation/range-selectors.md
@@ -4,7 +4,7 @@ title: Range selectors
 
 ## Range selectors
 
-Content between two elements in a document can be selected using a range selector, regardless of their DOM position. When no unique wrapper element exists for the whole terms content and their is no easy way to select the content with only CSS selectors, range selectors can be utilized. The concept is inspired by the [Range API](https://developer.mozilla.org/en-US/docs/Web/API/Range), where content is defined by start and end points that may be inclusive or exclusive. The format is defined as a JSON object in the following way:
+When no unique wrapper element exists for the whole terms content, there is no easy way to select the content with only CSS selectors. Content between two elements in a document can be selected using a range selector, regardless of their DOM position. The concept is inspired by the DOM [Range API](https://developer.mozilla.org/en-US/docs/Web/API/Range), where content is defined by start and end points that may be included or excluded. The format is defined as a JSON object:
 
 ```json
 {

From fb9225f714452451cc817d51c83716670ddcd116 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 2 Apr 2025 10:38:38 +0200
Subject: [PATCH 09/20] Unify plural

---
 content/analysis/how-to/_index.md                   |   2 +-
 content/analysis/reference/_index.md                |   2 +-
 content/api/cli.md                                  |   2 +-
 content/collections/how-to guides/_index.md         |   5 +++++
 .../create-repositories.md                          |   0
 .../collections/{how-to => how-to guides}/create.md |   6 +++---
 .../{how-to => how-to guides}/define-metadata.md    |   0
 .../reference => collections/references}/_index.md  |   2 +-
 .../{reference => references}/configuration.md      |   0
 .../environment-variables.md                        |   0
 .../{reference => references}/governance.md         |   0
 .../{reference => references}/metadata.md           |   2 +-
 content/community/how-to guides/_index.md           |   4 ++++
 .../join-community-chat.md                          |   0
 content/community/how-to/_index.md                  |   4 ----
 content/deployment/how-to guides/_index.md          |   4 ++++
 .../deployment/{how-to => how-to guides}/deploy.md  |   0
 .../{how-to => how-to guides}/setup-github-teams.md |   0
 content/deployment/how-to/_index.md                 |   4 ----
 content/federation/how-to guides/_index.md          |   4 ++++
 .../federation/{how-to => how-to guides}/join.md    |   0
 content/federation/how-to/_index.md                 |   4 ----
 content/federation/reference/_index.md              |   4 ----
 .../how-to => federation/references}/_index.md      |   3 +--
 .../{reference => references}/criteria.md           |   6 +++---
 content/terms/explanation/_index.md                 |   4 ----
 content/terms/explanations/_index.md                |   4 ++++
 .../declarations-maintenance.md                     |   0
 .../range-selectors.md                              |   0
 content/terms/guidelines/choosing-selectors.md      |   4 ++--
 content/terms/guidelines/reviewing.md               |   6 +++---
 content/terms/how-to guides/_index.md               |   4 ++++
 .../{how-to => how-to guides}/add-terms-using-UI.md |   0
 .../terms/{how-to => how-to guides}/be-notified.md  |   0
 ...ions-maintenance-inspector-open-get-datetime.png | Bin
 ...tions-maintenance-ota-bot-comment-last-month.png | Bin
 ...s-maintenance-ota-bot-comment-reopened-issue.png | Bin
 .../declarations-maintenance-ota-bot-comment.png    | Bin
 .../get-the-validUntil-date-from-an-issue.md        |   2 +-
 content/terms/how-to guides/rename-a-service.md     |   8 ++++++++
 .../terminate-a-service.md                          |   2 +-
 .../{how-to => how-to guides}/test-declaration.md   |   0
 .../{how-to => how-to guides}/track-new-terms.md    |   0
 content/terms/how-to/_index.md                      |   4 ----
 content/terms/how-to/rename-a-service.md            |   8 --------
 .../reference => terms/references}/_index.md        |   2 +-
 .../terms/{reference => references}/declaration.md  |   4 ++--
 .../terms/{explanation => references}/filters.md    |   0
 48 files changed, 55 insertions(+), 55 deletions(-)
 create mode 100644 content/collections/how-to guides/_index.md
 rename content/collections/{how-to => how-to guides}/create-repositories.md (100%)
 rename content/collections/{how-to => how-to guides}/create.md (85%)
 rename content/collections/{how-to => how-to guides}/define-metadata.md (100%)
 rename content/{terms/reference => collections/references}/_index.md (50%)
 rename content/collections/{reference => references}/configuration.md (100%)
 rename content/collections/{reference => references}/environment-variables.md (100%)
 rename content/collections/{reference => references}/governance.md (100%)
 rename content/collections/{reference => references}/metadata.md (99%)
 create mode 100644 content/community/how-to guides/_index.md
 rename content/community/{how-to => how-to guides}/join-community-chat.md (100%)
 delete mode 100644 content/community/how-to/_index.md
 create mode 100644 content/deployment/how-to guides/_index.md
 rename content/deployment/{how-to => how-to guides}/deploy.md (100%)
 rename content/deployment/{how-to => how-to guides}/setup-github-teams.md (100%)
 delete mode 100644 content/deployment/how-to/_index.md
 create mode 100644 content/federation/how-to guides/_index.md
 rename content/federation/{how-to => how-to guides}/join.md (100%)
 delete mode 100644 content/federation/how-to/_index.md
 delete mode 100644 content/federation/reference/_index.md
 rename content/{collections/how-to => federation/references}/_index.md (50%)
 rename content/federation/{reference => references}/criteria.md (95%)
 delete mode 100644 content/terms/explanation/_index.md
 create mode 100644 content/terms/explanations/_index.md
 rename content/terms/{explanation => explanations}/declarations-maintenance.md (100%)
 rename content/terms/{explanation => explanations}/range-selectors.md (100%)
 create mode 100644 content/terms/how-to guides/_index.md
 rename content/terms/{how-to => how-to guides}/add-terms-using-UI.md (100%)
 rename content/terms/{how-to => how-to guides}/be-notified.md (100%)
 rename content/terms/{how-to => how-to guides}/declarations-maintenance-inspector-open-get-datetime.png (100%)
 rename content/terms/{how-to => how-to guides}/declarations-maintenance-ota-bot-comment-last-month.png (100%)
 rename content/terms/{how-to => how-to guides}/declarations-maintenance-ota-bot-comment-reopened-issue.png (100%)
 rename content/terms/{how-to => how-to guides}/declarations-maintenance-ota-bot-comment.png (100%)
 rename content/terms/{how-to => how-to guides}/get-the-validUntil-date-from-an-issue.md (95%)
 create mode 100644 content/terms/how-to guides/rename-a-service.md
 rename content/terms/{how-to => how-to guides}/terminate-a-service.md (93%)
 rename content/terms/{how-to => how-to guides}/test-declaration.md (100%)
 rename content/terms/{how-to => how-to guides}/track-new-terms.md (100%)
 delete mode 100644 content/terms/how-to/_index.md
 delete mode 100644 content/terms/how-to/rename-a-service.md
 rename content/{collections/reference => terms/references}/_index.md (50%)
 rename content/terms/{reference => references}/declaration.md (98%)
 rename content/terms/{explanation => references}/filters.md (100%)

diff --git a/content/analysis/how-to/_index.md b/content/analysis/how-to/_index.md
index 537c3cba..b4ac9c61 100644
--- a/content/analysis/how-to/_index.md
+++ b/content/analysis/how-to/_index.md
@@ -1,4 +1,4 @@
 ---
-title: How to
+title: How to guides
 weight: 1
 ---
diff --git a/content/analysis/reference/_index.md b/content/analysis/reference/_index.md
index 6f4fd0f8..98ee9611 100644
--- a/content/analysis/reference/_index.md
+++ b/content/analysis/reference/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Reference
+title: References
 weight: 2
 ---
diff --git a/content/api/cli.md b/content/api/cli.md
index f8ee9cdc..6f486868 100644
--- a/content/api/cli.md
+++ b/content/api/cli.md
@@ -50,7 +50,7 @@ To export the dataset into a ZIP file and publish it on GitHub releases:
 
 {{< configOption name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish`" />}}
 
-The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/reference/environment-variables" >}}).
+The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/references/environment-variables" >}}).
 
 To export, publish the dataset and remove the local copy that was created after it has been uploaded:
 
diff --git a/content/collections/how-to guides/_index.md b/content/collections/how-to guides/_index.md
new file mode 100644
index 00000000..01a5161f
--- /dev/null
+++ b/content/collections/how-to guides/_index.md	
@@ -0,0 +1,5 @@
+---
+title: How to guides
+weight: 2
+---
+
diff --git a/content/collections/how-to/create-repositories.md b/content/collections/how-to guides/create-repositories.md
similarity index 100%
rename from content/collections/how-to/create-repositories.md
rename to content/collections/how-to guides/create-repositories.md
diff --git a/content/collections/how-to/create.md b/content/collections/how-to guides/create.md
similarity index 85%
rename from content/collections/how-to/create.md
rename to content/collections/how-to guides/create.md
index 2fb1ccd0..9abcddbf 100644
--- a/content/collections/how-to/create.md
+++ b/content/collections/how-to guides/create.md	
@@ -9,7 +9,7 @@ You are considering creating a new collection to track terms with Open Terms A
 
 ## Define metadata
 
-First of all, define the [metadata]({{< relref "collections/reference/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
+First of all, define the [metadata]({{< relref "collections/references/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
 
 ## Check existing collections
 
@@ -25,10 +25,10 @@ You can inform the community by posting on the instant messaging system, or [sen
 
 ## Define governance
 
-Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the [governance]({{< relref "collections/reference/governance" >}}) of your collection.
+Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the [governance]({{< relref "collections/references/governance" >}}) of your collection.
 
 At any time, feel free to ask for help or partners in the community.
 
 ## Create repositories
 
-See the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}}) for your collection.
+See the [guide to create repositories]({{< relref "collections/how-to-guides/create-repositories" >}}) for your collection.
diff --git a/content/collections/how-to/define-metadata.md b/content/collections/how-to guides/define-metadata.md
similarity index 100%
rename from content/collections/how-to/define-metadata.md
rename to content/collections/how-to guides/define-metadata.md
diff --git a/content/terms/reference/_index.md b/content/collections/references/_index.md
similarity index 50%
rename from content/terms/reference/_index.md
rename to content/collections/references/_index.md
index 63aae4a6..fd021bb8 100644
--- a/content/terms/reference/_index.md
+++ b/content/collections/references/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Reference
+title: References
 weight: 3
 ---
diff --git a/content/collections/reference/configuration.md b/content/collections/references/configuration.md
similarity index 100%
rename from content/collections/reference/configuration.md
rename to content/collections/references/configuration.md
diff --git a/content/collections/reference/environment-variables.md b/content/collections/references/environment-variables.md
similarity index 100%
rename from content/collections/reference/environment-variables.md
rename to content/collections/references/environment-variables.md
diff --git a/content/collections/reference/governance.md b/content/collections/references/governance.md
similarity index 100%
rename from content/collections/reference/governance.md
rename to content/collections/references/governance.md
diff --git a/content/collections/reference/metadata.md b/content/collections/references/metadata.md
similarity index 99%
rename from content/collections/reference/metadata.md
rename to content/collections/references/metadata.md
index f68e96d2..3a3a765f 100644
--- a/content/collections/reference/metadata.md
+++ b/content/collections/references/metadata.md
@@ -207,7 +207,7 @@ fr:
 {{< configOption
     name="roles"
     type="array of strings"
-    description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)"
+    description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/references/governance/)"
     allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`"
     example="[host, administrator]"
     required=true
diff --git a/content/community/how-to guides/_index.md b/content/community/how-to guides/_index.md
new file mode 100644
index 00000000..b4ac9c61
--- /dev/null
+++ b/content/community/how-to guides/_index.md	
@@ -0,0 +1,4 @@
+---
+title: How to guides
+weight: 1
+---
diff --git a/content/community/how-to/join-community-chat.md b/content/community/how-to guides/join-community-chat.md
similarity index 100%
rename from content/community/how-to/join-community-chat.md
rename to content/community/how-to guides/join-community-chat.md
diff --git a/content/community/how-to/_index.md b/content/community/how-to/_index.md
deleted file mode 100644
index 537c3cba..00000000
--- a/content/community/how-to/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: How to
-weight: 1
----
diff --git a/content/deployment/how-to guides/_index.md b/content/deployment/how-to guides/_index.md
new file mode 100644
index 00000000..b4ac9c61
--- /dev/null
+++ b/content/deployment/how-to guides/_index.md	
@@ -0,0 +1,4 @@
+---
+title: How to guides
+weight: 1
+---
diff --git a/content/deployment/how-to/deploy.md b/content/deployment/how-to guides/deploy.md
similarity index 100%
rename from content/deployment/how-to/deploy.md
rename to content/deployment/how-to guides/deploy.md
diff --git a/content/deployment/how-to/setup-github-teams.md b/content/deployment/how-to guides/setup-github-teams.md
similarity index 100%
rename from content/deployment/how-to/setup-github-teams.md
rename to content/deployment/how-to guides/setup-github-teams.md
diff --git a/content/deployment/how-to/_index.md b/content/deployment/how-to/_index.md
deleted file mode 100644
index 537c3cba..00000000
--- a/content/deployment/how-to/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: How to
-weight: 1
----
diff --git a/content/federation/how-to guides/_index.md b/content/federation/how-to guides/_index.md
new file mode 100644
index 00000000..b4ac9c61
--- /dev/null
+++ b/content/federation/how-to guides/_index.md	
@@ -0,0 +1,4 @@
+---
+title: How to guides
+weight: 1
+---
diff --git a/content/federation/how-to/join.md b/content/federation/how-to guides/join.md
similarity index 100%
rename from content/federation/how-to/join.md
rename to content/federation/how-to guides/join.md
diff --git a/content/federation/how-to/_index.md b/content/federation/how-to/_index.md
deleted file mode 100644
index 537c3cba..00000000
--- a/content/federation/how-to/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: How to
-weight: 1
----
diff --git a/content/federation/reference/_index.md b/content/federation/reference/_index.md
deleted file mode 100644
index 6f4fd0f8..00000000
--- a/content/federation/reference/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: Reference
-weight: 2
----
diff --git a/content/collections/how-to/_index.md b/content/federation/references/_index.md
similarity index 50%
rename from content/collections/how-to/_index.md
rename to content/federation/references/_index.md
index e5d7a8d9..98ee9611 100644
--- a/content/collections/how-to/_index.md
+++ b/content/federation/references/_index.md
@@ -1,5 +1,4 @@
 ---
-title: How to
+title: References
 weight: 2
 ---
-
diff --git a/content/federation/reference/criteria.md b/content/federation/references/criteria.md
similarity index 95%
rename from content/federation/reference/criteria.md
rename to content/federation/references/criteria.md
index a4c5a831..e2e8ae2c 100644
--- a/content/federation/reference/criteria.md
+++ b/content/federation/references/criteria.md
@@ -7,8 +7,8 @@ weight: 3
 
 A **collection** can **join** the Open Terms Archive **federation** if it abides by the following quality criteria:
 
-1. Clearly defined [collection metadata]({{< relref "collections/reference/metadata" >}}).
-2. Clearly defined [collection governance]({{< relref "collections/reference/governance" >}}).
+1. Clearly defined [collection metadata]({{< relref "collections/references/metadata" >}}).
+2. Clearly defined [collection governance]({{< relref "collections/references/governance" >}}).
 3. The vast majority of **versions** are readable, as evidenced by a sample assessment.
 4. **Frequency** of at least one track a day, as evidenced by snapshots.
 5. Public and open-licensed **declarations**, as evidenced by the `LICENSE` file in the declarations repository.
@@ -18,7 +18,7 @@ A **collection** can **join** the Open Terms Archive **federation** if it abides
 9. Publicly accessible API with median response time under 20ms, as evidenced by uptime tracking logs.
 10. Abide by all Open Terms Archive software and data licenses.
 
-For detailed instructions on joining the federation, refer to the [How to Join the Federation guide]({{< relref "federation/how-to/join" >}}).
+For detailed instructions on joining the federation, refer to the [How to Join the Federation guide]({{< relref "federation/how-to-guides/join" >}}).
 
 ## Disclaimer
 
diff --git a/content/terms/explanation/_index.md b/content/terms/explanation/_index.md
deleted file mode 100644
index 82b01122..00000000
--- a/content/terms/explanation/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: Explanation
-weight: 2
----
diff --git a/content/terms/explanations/_index.md b/content/terms/explanations/_index.md
new file mode 100644
index 00000000..b18c0ef5
--- /dev/null
+++ b/content/terms/explanations/_index.md
@@ -0,0 +1,4 @@
+---
+title: Explanations
+weight: 2
+---
diff --git a/content/terms/explanation/declarations-maintenance.md b/content/terms/explanations/declarations-maintenance.md
similarity index 100%
rename from content/terms/explanation/declarations-maintenance.md
rename to content/terms/explanations/declarations-maintenance.md
diff --git a/content/terms/explanation/range-selectors.md b/content/terms/explanations/range-selectors.md
similarity index 100%
rename from content/terms/explanation/range-selectors.md
rename to content/terms/explanations/range-selectors.md
diff --git a/content/terms/guidelines/choosing-selectors.md b/content/terms/guidelines/choosing-selectors.md
index 5b309088..341bddf9 100644
--- a/content/terms/guidelines/choosing-selectors.md
+++ b/content/terms/guidelines/choosing-selectors.md
@@ -9,7 +9,7 @@ Selectors are used in Open Terms Archive declarations to specify the parts of
 
 ## What are selectors
 
-Selectors are used in the [`select`]({{< relref "terms/reference#select" >}}) and [`remove`]({{< relref "terms/reference#remove" >}}) keys of an Open Terms Archive declaration.
+Selectors are used in the [`select`]({{< relref "terms/references#select" >}}) and [`remove`]({{< relref "terms/references#remove" >}}) keys of an Open Terms Archive declaration.
 
 The “selectors” referred to are defined by the [W3C Selectors standard](https://www.w3.org/TR/selectors/), more commonly known as “CSS Selectors”.
 
@@ -164,7 +164,7 @@ If in doubt about a selector, prefer making a wide selection and then removing t
 
 ### Use range selectors
 
-[Range selectors]({{< relref "terms/reference#range-selectors" >}}) enable to select content that starts in one block and ends in another block that are not in the same tree. While they are more complex than element selectors, it is preferable to use a range selector whose start and end abide by the guidelines above than to use a bad plain selector.
+[Range selectors]({{< relref "terms/references#range-selectors" >}}) enable to select content that starts in one block and ends in another block that are not in the same tree. While they are more complex than element selectors, it is preferable to use a range selector whose start and end abide by the guidelines above than to use a bad plain selector.
 
 #### Example
 
diff --git a/content/terms/guidelines/reviewing.md b/content/terms/guidelines/reviewing.md
index 0354592e..44dc52ef 100644
--- a/content/terms/guidelines/reviewing.md
+++ b/content/terms/guidelines/reviewing.md
@@ -72,7 +72,7 @@ The pull request created will consist of fewer checks than those that add declar
 
 For pull requests that update declarations, you should focus should be on two things: history file and declaration.
 
-- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/explanation/declarations-maintenance" >}}).
+- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/explanations/declarations-maintenance" >}}).
 - **Declaration:** for `update` pull requests, you only look at the selectors to make sure they are **simple** and also verify the **generated version** is ok.
 
 ### Step-by-step Review Guide
@@ -84,7 +84,7 @@ For pull requests that update declarations, you should focus should be on two th
 5. Compare it with the `validUntil` property in the history file under the `Files changes` section of the pull request. If the dates are the same, proceed to approve the pull request.
 6. Merge the contribution.
 
-You can read more about maintaining declarations from the [official documentation]({{< relref "terms/explanation/declarations-maintenance" >}}).
+You can read more about maintaining declarations from the [official documentation]({{< relref "terms/explanations/declarations-maintenance" >}}).
 
 ## When to Make Changes to a Contribution
 
@@ -94,7 +94,7 @@ In some special cases, the correction may have to do with the service name. Such
 
 ### Editing a Service ID
 
-When contributing to the project, reviewers may need to modify the Service ID of a service that is being added for tracking. This is often necessary when the service being tracked is in a language other than English, such as Chinese or French. In these cases, the Service ID usually reflects the transliteration of the service name (written in the native language). The [documentation]({{< relref "terms/reference#service-id" >}}) provides more information on this. It is important to note that the contributor can be very crucial in providing an accurate transliteration of the service name especially if the reviewer does not know the service's native language.
+When contributing to the project, reviewers may need to modify the Service ID of a service that is being added for tracking. This is often necessary when the service being tracked is in a language other than English, such as Chinese or French. In these cases, the Service ID usually reflects the transliteration of the service name (written in the native language). The [documentation]({{< relref "terms/references#service-id" >}}) provides more information on this. It is important to note that the contributor can be very crucial in providing an accurate transliteration of the service name especially if the reviewer does not know the service's native language.
 
 Since the Service ID is used as the file name of the JSON file associated with the service, it is necessary to change the file name to reflect the transliteration. Here are the steps to follow:
 
diff --git a/content/terms/how-to guides/_index.md b/content/terms/how-to guides/_index.md
new file mode 100644
index 00000000..d6db9c3c
--- /dev/null
+++ b/content/terms/how-to guides/_index.md	
@@ -0,0 +1,4 @@
+---
+title: How to guides
+weight: 2
+---
diff --git a/content/terms/how-to/add-terms-using-UI.md b/content/terms/how-to guides/add-terms-using-UI.md
similarity index 100%
rename from content/terms/how-to/add-terms-using-UI.md
rename to content/terms/how-to guides/add-terms-using-UI.md
diff --git a/content/terms/how-to/be-notified.md b/content/terms/how-to guides/be-notified.md
similarity index 100%
rename from content/terms/how-to/be-notified.md
rename to content/terms/how-to guides/be-notified.md
diff --git a/content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png b/content/terms/how-to guides/declarations-maintenance-inspector-open-get-datetime.png
similarity index 100%
rename from content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png
rename to content/terms/how-to guides/declarations-maintenance-inspector-open-get-datetime.png
diff --git a/content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png b/content/terms/how-to guides/declarations-maintenance-ota-bot-comment-last-month.png
similarity index 100%
rename from content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png
rename to content/terms/how-to guides/declarations-maintenance-ota-bot-comment-last-month.png
diff --git a/content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png b/content/terms/how-to guides/declarations-maintenance-ota-bot-comment-reopened-issue.png
similarity index 100%
rename from content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png
rename to content/terms/how-to guides/declarations-maintenance-ota-bot-comment-reopened-issue.png
diff --git a/content/terms/how-to/declarations-maintenance-ota-bot-comment.png b/content/terms/how-to guides/declarations-maintenance-ota-bot-comment.png
similarity index 100%
rename from content/terms/how-to/declarations-maintenance-ota-bot-comment.png
rename to content/terms/how-to guides/declarations-maintenance-ota-bot-comment.png
diff --git a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md b/content/terms/how-to guides/get-the-validUntil-date-from-an-issue.md
similarity index 95%
rename from content/terms/how-to/get-the-validUntil-date-from-an-issue.md
rename to content/terms/how-to guides/get-the-validUntil-date-from-an-issue.md
index 4478d4b2..ec255e55 100644
--- a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md
+++ b/content/terms/how-to guides/get-the-validUntil-date-from-an-issue.md	
@@ -1,5 +1,5 @@
 ---
-title: How to get the `validUntil`
+title: How to guides get the `validUntil`
 linkTitle: Get the `validUntil` date
 ---
 
diff --git a/content/terms/how-to guides/rename-a-service.md b/content/terms/how-to guides/rename-a-service.md
new file mode 100644
index 00000000..ed04279d
--- /dev/null
+++ b/content/terms/how-to guides/rename-a-service.md	
@@ -0,0 +1,8 @@
+---
+title: How to guides rename a service
+linkTitle: Rename a service
+---
+
+# How to rename a service
+
+The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to-guides/track-new-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms.
diff --git a/content/terms/how-to/terminate-a-service.md b/content/terms/how-to guides/terminate-a-service.md
similarity index 93%
rename from content/terms/how-to/terminate-a-service.md
rename to content/terms/how-to guides/terminate-a-service.md
index 7c3a923b..c0ce5ffb 100644
--- a/content/terms/how-to/terminate-a-service.md
+++ b/content/terms/how-to guides/terminate-a-service.md	
@@ -1,5 +1,5 @@
 ---
-title: How to terminate a service
+title: How to guides terminate a service
 linkTitle: Terminate a service
 ---
 
diff --git a/content/terms/how-to/test-declaration.md b/content/terms/how-to guides/test-declaration.md
similarity index 100%
rename from content/terms/how-to/test-declaration.md
rename to content/terms/how-to guides/test-declaration.md
diff --git a/content/terms/how-to/track-new-terms.md b/content/terms/how-to guides/track-new-terms.md
similarity index 100%
rename from content/terms/how-to/track-new-terms.md
rename to content/terms/how-to guides/track-new-terms.md
diff --git a/content/terms/how-to/_index.md b/content/terms/how-to/_index.md
deleted file mode 100644
index 6b204c17..00000000
--- a/content/terms/how-to/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: How to
-weight: 2
----
diff --git a/content/terms/how-to/rename-a-service.md b/content/terms/how-to/rename-a-service.md
deleted file mode 100644
index 59871a5c..00000000
--- a/content/terms/how-to/rename-a-service.md
+++ /dev/null
@@ -1,8 +0,0 @@
----
-title: How to rename a service
-linkTitle: Rename a service
----
-
-# How to rename a service
-
-The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to/track-new-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms.
diff --git a/content/collections/reference/_index.md b/content/terms/references/_index.md
similarity index 50%
rename from content/collections/reference/_index.md
rename to content/terms/references/_index.md
index 63aae4a6..fd021bb8 100644
--- a/content/collections/reference/_index.md
+++ b/content/terms/references/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Reference
+title: References
 weight: 3
 ---
diff --git a/content/terms/reference/declaration.md b/content/terms/references/declaration.md
similarity index 98%
rename from content/terms/reference/declaration.md
rename to content/terms/references/declaration.md
index c29077c8..da4e5ea1 100644
--- a/content/terms/reference/declaration.md
+++ b/content/terms/references/declaration.md
@@ -1,6 +1,6 @@
 ---
 title: "Service declaration"
-aliases: "/terms/reference/"
+aliases: "/terms/references/"
 ---
 
 # Service declaration
@@ -141,7 +141,7 @@ As an array of those:
 {{< configOption
     name="filter"
     type="array of strings"
-    description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"/terms/explanation/filters\" >}}) section for more information."
+    description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"terms/references/filters\" >}}) section for more information."
     example="[\"filterName1\", \"filterName2\"]"
 />}}
 
diff --git a/content/terms/explanation/filters.md b/content/terms/references/filters.md
similarity index 100%
rename from content/terms/explanation/filters.md
rename to content/terms/references/filters.md

From 2ffe7a939fd03b5d0f5083fc0f1cfe4394c4e9c9 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 2 Apr 2025 10:46:43 +0200
Subject: [PATCH 10/20] Improve example

Co-authored-by: Matti Schneider <matti@opentermsarchive.org>
---
 content/terms/explanations/range-selectors.md | 60 +++++++------------
 1 file changed, 20 insertions(+), 40 deletions(-)

diff --git a/content/terms/explanations/range-selectors.md b/content/terms/explanations/range-selectors.md
index 9b9a9d6d..5194574a 100644
--- a/content/terms/explanations/range-selectors.md
+++ b/content/terms/explanations/range-selectors.md
@@ -23,63 +23,43 @@ Let's take an example to see when range selectors can be useful. Given the follo
 <body>
   <main>
     <!-- Breadcrumb Navigation -->
-    <div>
-      <ol>
-        <li><a href="/">Home</a></li>
-        <li><a href="/legal">Legal</a></li>
-        <li>Terms and Conditions</li>
-      </ol>
-    </div>
-
-    <!-- Sub Navigation -->
-    <div>
-      <nav>
-        <ul>
-          <li>
-            <a href="/legal/terms">Terms and Conditions</a>
-          </li>
-          <li>
-            <a href="/legal/privacy">Privacy Policy</a>
-          </li>
-        </ul>
-      </nav>
-    </div>
+    <ul>
+      <li><a href="/">Home</a></li>
+      <li>Terms and Conditions</li>
+    </ul>
 
     <!-- Main Content -->
-    <h1><a id="terms-title" href="#terms-title">Example Terms</a></h1>
+    <h1 id="terms-title">Example Terms</h1>
     <p>Effective as of: January 1, 2024</p>
 
-    <h2><a id="section-1" href="#section-1">1. Introduction</a></h2>
-    <p>These are example terms and conditions.</p>
+    <h2>Authorized uses</h2>
+    <p>You can use this service in the following cases:</p>
 
-    <h2><a id="section-2" href="#section-2">2. Usage</a></h2>
-    <p>Sample usage guidelines go here.</p>
+    <ul>
+      <li>At home</li>
+      <li>In your office</li>
+      <li>In a coffee shop</li>
+    </ul>
   </main>
-
-
-  <footer id="page-footer">
-    <nav>
-      <div>
-        <ul>
-          <li><a href="/about">About</a></li>
-          <li><a href="/contact">Contact</a></li>
-        </ul>
-      </div>
-    </nav>
-  </footer>
+  <div>
+    <ul id="footer-menu">
+      <li><a href="/about">About</a></li>
+      <li><a href="/contact">Contact</a></li>
+    </ul>
+  </div>
 </body>
 
 </html>
 ```
 
-In this case, there is no unique wrapper element for the terms content which is represented by all elements after the main title in the `main` element. Here selecting the whole `main` would result in selecting elements that are not part of the terms content, like the breadcrumb and sub navigation. The range selector can be used to select the terms content by specifying the main title `#terms-title` as the start point and the footer `#page-footer` as the end point. The selection starts *before* the main title, so it includes it, and ends *before* the footer, so it excludes it.
+In this case, there is no unique wrapper element for the terms content which is represented by all elements after the main title in the `main` element. Here selecting the whole `main` would result in selecting elements that are not part of the terms content, like the breadcrumb and sub navigation. The range selector can be used to select the terms content by specifying the main title `#terms-title` as the start point and the footer `#footer-menu` as the end point. The selection starts *before* the main title, so it includes it, and ends *before* the footer, so it excludes it.
 
 So the resulting range selector is:
 
 ```json
 {
   "startBefore": "#terms-title",
-  "endBefore": "#page-footer"
+  "endBefore": "#footer-menu"
 }
 ```
 

From 5baeddc691fa39d61a94f011eecef6d0aec5d724 Mon Sep 17 00:00:00 2001
From: Nicolas Dupont <npg.dupont@gmail.com>
Date: Wed, 2 Apr 2025 11:04:28 +0200
Subject: [PATCH 11/20] Fix typo

---
 content/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/_index.md b/content/_index.md
index 8a120245..fb105180 100644
--- a/content/_index.md
+++ b/content/_index.md
@@ -24,7 +24,7 @@ This documentation follows the [Diátaxis](https://diataxis.fr) approach and str
 
 - **Tutorials:** step-by-step learning guides that help beginners get started with Open Terms Archive, providing foundational knowledge and hands-on experience.
 - **How-to guides:** task-focused instructions that help experienced users accomplish specific goals efficiently and effectively.
-- **Reference:** comprehensive technical documentation detailing configuration options and specifications for advanced users.
+- **References:** comprehensive technical documentation detailing configuration options and specifications for advanced users.
 - **Explanations:** background knowledge that enables understanding the constraints and how choices that are made.
 
 ### Table of contents

From 5ac9fb1893034aeef87cd7a6f29aa20ab582952a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 11:13:53 +0200
Subject: [PATCH 12/20] =?UTF-8?q?Pluralise=20=E2=80=98how=20to=E2=80=98?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../analysis/{how-to => how-to-guides}/_index.md    |   0
 .../{how-to => how-to-guides}/navigate-history.md   |   1 +
 .../{how-to => how-to-guides}/publish-memo.md       |   4 +++-
 .../{how-to guides => how-to-guides}/_index.md      |   0
 .../create-repositories.md                          |   2 ++
 .../{how-to guides => how-to-guides}/create.md      |   2 ++
 .../define-metadata.md                              |   2 ++
 .../{how-to guides => how-to-guides}/_index.md      |   0
 .../join-community-chat.md                          |   1 +
 .../{how-to guides => how-to-guides}/_index.md      |   0
 .../{how-to guides => how-to-guides}/deploy.md      |   2 ++
 .../setup-github-teams.md                           |   2 ++
 .../{how-to guides => how-to-guides}/_index.md      |   0
 .../{how-to guides => how-to-guides}/join.md        |   2 ++
 .../{how-to guides => how-to-guides}/_index.md      |   0
 .../add-terms-using-UI.md                           |   4 +++-
 .../{how-to guides => how-to-guides}/be-notified.md |   3 ++-
 ...ions-maintenance-inspector-open-get-datetime.png | Bin
 ...tions-maintenance-ota-bot-comment-last-month.png | Bin
 ...s-maintenance-ota-bot-comment-reopened-issue.png | Bin
 .../declarations-maintenance-ota-bot-comment.png    | Bin
 .../get-the-validUntil-date-from-an-issue.md        |   2 ++
 .../rename-a-service.md                             |   2 ++
 .../terminate-a-service.md                          |   2 ++
 .../test-declaration.md                             |   0
 .../track-new-terms.md                              |   4 +++-
 26 files changed, 31 insertions(+), 4 deletions(-)
 rename content/analysis/{how-to => how-to-guides}/_index.md (100%)
 rename content/analysis/{how-to => how-to-guides}/navigate-history.md (99%)
 rename content/analysis/{how-to => how-to-guides}/publish-memo.md (96%)
 rename content/collections/{how-to guides => how-to-guides}/_index.md (100%)
 rename content/collections/{how-to guides => how-to-guides}/create-repositories.md (98%)
 rename content/collections/{how-to guides => how-to-guides}/create.md (97%)
 rename content/collections/{how-to guides => how-to-guides}/define-metadata.md (98%)
 rename content/community/{how-to guides => how-to-guides}/_index.md (100%)
 rename content/community/{how-to guides => how-to-guides}/join-community-chat.md (98%)
 rename content/deployment/{how-to guides => how-to-guides}/_index.md (100%)
 rename content/deployment/{how-to guides => how-to-guides}/deploy.md (99%)
 rename content/deployment/{how-to guides => how-to-guides}/setup-github-teams.md (97%)
 rename content/federation/{how-to guides => how-to-guides}/_index.md (100%)
 rename content/federation/{how-to guides => how-to-guides}/join.md (95%)
 rename content/terms/{how-to guides => how-to-guides}/_index.md (100%)
 rename content/terms/{how-to guides => how-to-guides}/add-terms-using-UI.md (88%)
 rename content/terms/{how-to guides => how-to-guides}/be-notified.md (92%)
 rename content/terms/{how-to guides => how-to-guides}/declarations-maintenance-inspector-open-get-datetime.png (100%)
 rename content/terms/{how-to guides => how-to-guides}/declarations-maintenance-ota-bot-comment-last-month.png (100%)
 rename content/terms/{how-to guides => how-to-guides}/declarations-maintenance-ota-bot-comment-reopened-issue.png (100%)
 rename content/terms/{how-to guides => how-to-guides}/declarations-maintenance-ota-bot-comment.png (100%)
 rename content/terms/{how-to guides => how-to-guides}/get-the-validUntil-date-from-an-issue.md (93%)
 rename content/terms/{how-to guides => how-to-guides}/rename-a-service.md (94%)
 rename content/terms/{how-to guides => how-to-guides}/terminate-a-service.md (93%)
 rename content/terms/{how-to guides => how-to-guides}/test-declaration.md (100%)
 rename content/terms/{how-to guides => how-to-guides}/track-new-terms.md (98%)

diff --git a/content/analysis/how-to/_index.md b/content/analysis/how-to-guides/_index.md
similarity index 100%
rename from content/analysis/how-to/_index.md
rename to content/analysis/how-to-guides/_index.md
diff --git a/content/analysis/how-to/navigate-history.md b/content/analysis/how-to-guides/navigate-history.md
similarity index 99%
rename from content/analysis/how-to/navigate-history.md
rename to content/analysis/how-to-guides/navigate-history.md
index 350cb88b..9b47b218 100644
--- a/content/analysis/how-to/navigate-history.md
+++ b/content/analysis/how-to-guides/navigate-history.md
@@ -4,6 +4,7 @@ weight: 1
 aliases:
   - /navigate-history/
   - /terms/how-to-navigate-history/
+  - /analysis/how-to/navigate-history/
 ---
 
 # How to navigate history
diff --git a/content/analysis/how-to/publish-memo.md b/content/analysis/how-to-guides/publish-memo.md
similarity index 96%
rename from content/analysis/how-to/publish-memo.md
rename to content/analysis/how-to-guides/publish-memo.md
index 31e57696..0246fcf0 100644
--- a/content/analysis/how-to/publish-memo.md
+++ b/content/analysis/how-to-guides/publish-memo.md
@@ -1,6 +1,8 @@
 ---
 title: Publish a memo
-aliases: /memos/how-to-publish/
+aliases: 
+  - /memos/how-to-publish/
+  - /analysis/how-to/publish-memo/
 ---
 
 # How to publish a memo
diff --git a/content/collections/how-to guides/_index.md b/content/collections/how-to-guides/_index.md
similarity index 100%
rename from content/collections/how-to guides/_index.md
rename to content/collections/how-to-guides/_index.md
diff --git a/content/collections/how-to guides/create-repositories.md b/content/collections/how-to-guides/create-repositories.md
similarity index 98%
rename from content/collections/how-to guides/create-repositories.md
rename to content/collections/how-to-guides/create-repositories.md
index b9b2b3d9..4b737cf0 100644
--- a/content/collections/how-to guides/create-repositories.md	
+++ b/content/collections/how-to-guides/create-repositories.md
@@ -1,6 +1,8 @@
 ---
 title: Create repositories
 weight: 1
+aliases:
+  - /collections/how-to/create-repositories/
 ---
 
 # How to create collection repositories
diff --git a/content/collections/how-to guides/create.md b/content/collections/how-to-guides/create.md
similarity index 97%
rename from content/collections/how-to guides/create.md
rename to content/collections/how-to-guides/create.md
index 9abcddbf..3fff3c1e 100644
--- a/content/collections/how-to guides/create.md	
+++ b/content/collections/how-to-guides/create.md
@@ -1,6 +1,8 @@
 ---
 title: Create a collection
 weight: 3
+aliases:
+  - /collections/how-to/define-metadata/
 ---
 
 # How to create a collection
diff --git a/content/collections/how-to guides/define-metadata.md b/content/collections/how-to-guides/define-metadata.md
similarity index 98%
rename from content/collections/how-to guides/define-metadata.md
rename to content/collections/how-to-guides/define-metadata.md
index bffe5c67..8bb84938 100644
--- a/content/collections/how-to guides/define-metadata.md	
+++ b/content/collections/how-to-guides/define-metadata.md
@@ -1,6 +1,8 @@
 ---
 title: Define metadata
 weight: 2
+aliases:
+  - /collections/how-to/create/
 ---
 
 # How to define metadata
diff --git a/content/community/how-to guides/_index.md b/content/community/how-to-guides/_index.md
similarity index 100%
rename from content/community/how-to guides/_index.md
rename to content/community/how-to-guides/_index.md
diff --git a/content/community/how-to guides/join-community-chat.md b/content/community/how-to-guides/join-community-chat.md
similarity index 98%
rename from content/community/how-to guides/join-community-chat.md
rename to content/community/how-to-guides/join-community-chat.md
index 425d9f8b..5ad18c0d 100644
--- a/content/community/how-to guides/join-community-chat.md	
+++ b/content/community/how-to-guides/join-community-chat.md
@@ -3,6 +3,7 @@ title: Join the community chat
 aliases:
   - /community/how-to-join-mattermost/
   - /community/how-to/join-mattermost/
+  - /community/how-to/join-community-chat/
 linkTitle: Join the chat
 ---
 
diff --git a/content/deployment/how-to guides/_index.md b/content/deployment/how-to-guides/_index.md
similarity index 100%
rename from content/deployment/how-to guides/_index.md
rename to content/deployment/how-to-guides/_index.md
diff --git a/content/deployment/how-to guides/deploy.md b/content/deployment/how-to-guides/deploy.md
similarity index 99%
rename from content/deployment/how-to guides/deploy.md
rename to content/deployment/how-to-guides/deploy.md
index ed9f6356..39e9f241 100644
--- a/content/deployment/how-to guides/deploy.md	
+++ b/content/deployment/how-to-guides/deploy.md
@@ -1,6 +1,8 @@
 ---
 title: Deploy a collection
 weight: 1
+aliases:
+  - /deployment/how-to/deploy/
 ---
 
 # How to deploy a collection
diff --git a/content/deployment/how-to guides/setup-github-teams.md b/content/deployment/how-to-guides/setup-github-teams.md
similarity index 97%
rename from content/deployment/how-to guides/setup-github-teams.md
rename to content/deployment/how-to-guides/setup-github-teams.md
index f2cf3b8f..79c0a93a 100644
--- a/content/deployment/how-to guides/setup-github-teams.md	
+++ b/content/deployment/how-to-guides/setup-github-teams.md
@@ -1,6 +1,8 @@
 ---
 title: Set up GitHub teams
 weight: 2
+aliases:
+  - /deployment/how-to/setup-github-teams/
 ---
 
 # How to set up GitHub teams for a collection
diff --git a/content/federation/how-to guides/_index.md b/content/federation/how-to-guides/_index.md
similarity index 100%
rename from content/federation/how-to guides/_index.md
rename to content/federation/how-to-guides/_index.md
diff --git a/content/federation/how-to guides/join.md b/content/federation/how-to-guides/join.md
similarity index 95%
rename from content/federation/how-to guides/join.md
rename to content/federation/how-to-guides/join.md
index 7e07c071..3605c00a 100644
--- a/content/federation/how-to guides/join.md	
+++ b/content/federation/how-to-guides/join.md
@@ -1,6 +1,8 @@
 ---
 title: Join the federation
 weight: 3
+aliases:
+  - /federation/how-to/join/
 ---
 
 # How to join the federation
diff --git a/content/terms/how-to guides/_index.md b/content/terms/how-to-guides/_index.md
similarity index 100%
rename from content/terms/how-to guides/_index.md
rename to content/terms/how-to-guides/_index.md
diff --git a/content/terms/how-to guides/add-terms-using-UI.md b/content/terms/how-to-guides/add-terms-using-UI.md
similarity index 88%
rename from content/terms/how-to guides/add-terms-using-UI.md
rename to content/terms/how-to-guides/add-terms-using-UI.md
index 813541b7..29856936 100644
--- a/content/terms/how-to guides/add-terms-using-UI.md	
+++ b/content/terms/how-to-guides/add-terms-using-UI.md
@@ -1,7 +1,9 @@
 ---
 title: Add terms with the graphical contribution interface
 linkTitle: Add terms with UI
-aliases: /terms/how-to-add-terms-using-with-the-graphical-contribution-interface/
+aliases: 
+  - /terms/how-to-add-terms-using-with-the-graphical-contribution-interface/
+  - /terms/how-to/add-terms-using-ui/
 ---
 
 # How to add terms with the graphical contribution interface
diff --git a/content/terms/how-to guides/be-notified.md b/content/terms/how-to-guides/be-notified.md
similarity index 92%
rename from content/terms/how-to guides/be-notified.md
rename to content/terms/how-to-guides/be-notified.md
index b9b9dd5f..d2450eca 100644
--- a/content/terms/how-to guides/be-notified.md	
+++ b/content/terms/how-to-guides/be-notified.md
@@ -3,6 +3,7 @@ title: Be notified of terms changes
 aliases:
   - /subscribe-rss/
   - /terms/how-to-be-notified-of-terms-changes/
+  - /terms/how-to/be-notified/
 ---
 
 # How to be notified of terms changes
@@ -15,7 +16,7 @@ An RSS feed is a type of web page that contains information about the latest con
 
 To find out the address of the RSS feed you want to subscribe to:
 
-1. [Navigate]({{< relref "/analysis/how-to/navigate-history" >}}) to the page with the history of changes you are interested in.
+1. [Navigate]({{< relref "/analysis/how-to-guides/navigate-history" >}}) to the page with the history of changes you are interested in.
     - For example, for the GitHub Privacy Policy of the Demo collection, this would be [this page](https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md).
 2. Copy the address of that page from your browser’s address bar.
     - For example, for the GitHub Privacy Policy of the Demo collection, this would be `https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md`.
diff --git a/content/terms/how-to guides/declarations-maintenance-inspector-open-get-datetime.png b/content/terms/how-to-guides/declarations-maintenance-inspector-open-get-datetime.png
similarity index 100%
rename from content/terms/how-to guides/declarations-maintenance-inspector-open-get-datetime.png
rename to content/terms/how-to-guides/declarations-maintenance-inspector-open-get-datetime.png
diff --git a/content/terms/how-to guides/declarations-maintenance-ota-bot-comment-last-month.png b/content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-last-month.png
similarity index 100%
rename from content/terms/how-to guides/declarations-maintenance-ota-bot-comment-last-month.png
rename to content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-last-month.png
diff --git a/content/terms/how-to guides/declarations-maintenance-ota-bot-comment-reopened-issue.png b/content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-reopened-issue.png
similarity index 100%
rename from content/terms/how-to guides/declarations-maintenance-ota-bot-comment-reopened-issue.png
rename to content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-reopened-issue.png
diff --git a/content/terms/how-to guides/declarations-maintenance-ota-bot-comment.png b/content/terms/how-to-guides/declarations-maintenance-ota-bot-comment.png
similarity index 100%
rename from content/terms/how-to guides/declarations-maintenance-ota-bot-comment.png
rename to content/terms/how-to-guides/declarations-maintenance-ota-bot-comment.png
diff --git a/content/terms/how-to guides/get-the-validUntil-date-from-an-issue.md b/content/terms/how-to-guides/get-the-validUntil-date-from-an-issue.md
similarity index 93%
rename from content/terms/how-to guides/get-the-validUntil-date-from-an-issue.md
rename to content/terms/how-to-guides/get-the-validUntil-date-from-an-issue.md
index ec255e55..6c8ceb6c 100644
--- a/content/terms/how-to guides/get-the-validUntil-date-from-an-issue.md	
+++ b/content/terms/how-to-guides/get-the-validUntil-date-from-an-issue.md
@@ -1,6 +1,8 @@
 ---
 title: How to guides get the `validUntil`
 linkTitle: Get the `validUntil` date
+aliases:
+  - /terms/how-to/get-the-validuntil-date-from-an-issue/
 ---
 
 # How to get the `validUntil` date
diff --git a/content/terms/how-to guides/rename-a-service.md b/content/terms/how-to-guides/rename-a-service.md
similarity index 94%
rename from content/terms/how-to guides/rename-a-service.md
rename to content/terms/how-to-guides/rename-a-service.md
index ed04279d..33e89281 100644
--- a/content/terms/how-to guides/rename-a-service.md	
+++ b/content/terms/how-to-guides/rename-a-service.md
@@ -1,6 +1,8 @@
 ---
 title: How to guides rename a service
 linkTitle: Rename a service
+aliases:
+  - /terms/how-to/rename-a-service/
 ---
 
 # How to rename a service
diff --git a/content/terms/how-to guides/terminate-a-service.md b/content/terms/how-to-guides/terminate-a-service.md
similarity index 93%
rename from content/terms/how-to guides/terminate-a-service.md
rename to content/terms/how-to-guides/terminate-a-service.md
index c0ce5ffb..6978a6be 100644
--- a/content/terms/how-to guides/terminate-a-service.md	
+++ b/content/terms/how-to-guides/terminate-a-service.md
@@ -1,6 +1,8 @@
 ---
 title: How to guides terminate a service
 linkTitle: Terminate a service
+aliases:
+  - /terms/how-to/terminate-a-service/
 ---
 
 # How to terminate a service
diff --git a/content/terms/how-to guides/test-declaration.md b/content/terms/how-to-guides/test-declaration.md
similarity index 100%
rename from content/terms/how-to guides/test-declaration.md
rename to content/terms/how-to-guides/test-declaration.md
diff --git a/content/terms/how-to guides/track-new-terms.md b/content/terms/how-to-guides/track-new-terms.md
similarity index 98%
rename from content/terms/how-to guides/track-new-terms.md
rename to content/terms/how-to-guides/track-new-terms.md
index 38f1b799..fce8928f 100644
--- a/content/terms/how-to guides/track-new-terms.md	
+++ b/content/terms/how-to-guides/track-new-terms.md
@@ -1,7 +1,9 @@
 ---
 title: Track new terms
 weight: 2
-aliases: /contributing-terms/
+aliases: 
+  - /contributing-terms/
+  - /terms/how-to/track-new-terms/
 ---
 
 # How to track new terms

From da8db53b27853e95ed374eb0459464f63e3677ee Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 15:34:17 +0200
Subject: [PATCH 13/20] Remove formating from value

---
 content/api/cli.md                            | 32 ++++----
 .../collections/references/configuration.md   | 76 +++++++++----------
 content/collections/references/metadata.md    |  2 +-
 .../layouts/shortcodes/configOption.html      | 15 +++-
 4 files changed, 68 insertions(+), 57 deletions(-)

diff --git a/content/api/cli.md b/content/api/cli.md
index 6f486868..bd0eef03 100644
--- a/content/api/cli.md
+++ b/content/api/cli.md
@@ -14,50 +14,50 @@ In these commands:
 
 ## Tracking terms
 
-{{< configOption name="ota track" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="`npx ota track`" />}}
+{{< configOption name="ota track" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="npx ota track" />}}
 
 > Note that the snapshots and versions will be recorded at the moment the command is executed, on top of the existing local history. If a shared history already exists and the goal is to add on top of it, that history has to be downloaded before executing that command.
 
-{{< configOption name="ota track --help" description="Show help and available options for track command" example="`npx ota track --help`" />}}
+{{< configOption name="ota track --help" description="Show help and available options for track command" example="npx ota track --help" />}}
 
-{{< configOption name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\"`" />}}
+{{< configOption name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="npx ota track --services \"Facebook\" \"LinkedIn\"" />}}
 
-{{< configOption name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" />}}
+{{< configOption name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
 
-{{< configOption name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="`npx ota track --schedule`" />}}
+{{< configOption name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="npx ota track --schedule" />}}
 
 ## Validating declarations
 
-{{< configOption name="ota validate [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="`npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" />}}
+{{< configOption name="ota validate [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
 
-{{< configOption name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="`npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" />}}
+{{< configOption name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
 
-{{< configOption name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="`npx ota validate --modified`" />}}
+{{< configOption name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="npx ota validate --modified" />}}
 
 ## Linting declarations
 
-{{< configOption name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="`npx ota lint --services \"Facebook\" \"LinkedIn\"`" />}}
+{{< configOption name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="npx ota lint --services \"Facebook\" \"LinkedIn\"" />}}
 
-{{< configOption name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="`npx ota lint --fix`" />}}
+{{< configOption name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="npx ota lint --fix" />}}
 
-{{< configOption name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="`npx ota lint --modified`" />}}
+{{< configOption name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="npx ota lint --modified" />}}
 
 ## Publishing dataset
 
-{{< configOption name="ota dataset [--file <filename>]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="`npx ota dataset --file dataset.zip`" />}}
+{{< configOption name="ota dataset [--file <filename>]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="npx ota dataset --file dataset.zip" />}}
 
 To export the dataset into a ZIP file and publish it on GitHub releases:
 
-{{< configOption name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish`" />}}
+{{< configOption name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish" />}}
 
 The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/references/environment-variables" >}}).
 
 To export, publish the dataset and remove the local copy that was created after it has been uploaded:
 
-{{< configOption name="ota dataset --publish --remove-local-copy [--file <filename>]" description="Export, publish dataset and remove local copy after upload" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy`" />}}
+{{< configOption name="ota dataset --publish --remove-local-copy [--file <filename>]" description="Export, publish dataset and remove local copy after upload" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy" />}}
 
-{{< configOption name="ota dataset --schedule [--file <filename>]" description="Schedule export, publishing and local copy removal" example="`GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy`" />}}
+{{< configOption name="ota dataset --schedule [--file <filename>]" description="Schedule export, publishing and local copy removal" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy" />}}
 
 ## Exposing the collection API
 
-{{< configOption name="ota serve" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="`npx ota serve`" />}}
+{{< configOption name="ota serve" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="npx ota serve" />}}
diff --git a/content/collections/references/configuration.md b/content/collections/references/configuration.md
index 127ccb83..a08aad23 100644
--- a/content/collections/references/configuration.md
+++ b/content/collections/references/configuration.md
@@ -14,16 +14,16 @@ As an example, see the [production configuration file](https://github.com/OpenTe
 {{< configOption
     name="trackingSchedule"
     type="string"
-    description="Defines how often the engine should check for changes in terms. Uses standard cron syntax to set the schedule."
-    default="`30 */12 * * *` (runs every 12 hours at minute 30)"
+    description="Defines how often the engine should check for changes in terms. Uses standard cron syntax to set the schedule. By default, it runs every 12 hours at minute 30."
+    default="30 */12 * * *"
 />}}
 
 {{< configOption
     name="collectionPath"
     type="string"
     description="Path to the collection's directory containing declarations directory and metadata file, relative to the engine execution location"
-    example="`../collections/demo-declarations`"
-    default="`./`"
+    example="../collections/demo-declarations"
+    default="./"
 />}}
 
 ### Recorder
@@ -50,21 +50,21 @@ The fetcher section configures how the engine retrieves documents from the web.
     name="fetcher.waitForElementsTimeout"
     type="number"
     description="Maximum wait time for elements to appear in a page (milliseconds)."
-    default="`10000`"
+    default="10000"
 />}}
 
 {{< configOption
     name="fetcher.navigationTimeout"
     type="number"
     description="Maximum wait time for a page to load (milliseconds)."
-    default="`30000`"
+    default="30000"
 />}}
 
 {{< configOption
     name="fetcher.language"
     type="string"
     description="Language code (ISO 639-1) for request headers."
-    default="`en`"
+    default="en"
 />}}
 
 ### Notifier
@@ -75,14 +75,14 @@ The notifier section sets up how notifications are sent when new versions of ter
     name="notifier.sendInBlue.updatesListId"
     type="string"
     description="SendInBlue contacts list ID of persons to notify on terms updates."
-    default="`850`"
+    default="850"
 />}}
 
 {{< configOption
     name="notifier.sendInBlue.updateTemplateId"
     type="string"
     description="SendInBlue email template ID used for updates notifications."
-    default="`7`"
+    default="7"
 />}}
 
 ### Logger
@@ -93,42 +93,42 @@ The logger section configures logging and error notification settings.
     name="logger.smtp.host"
     type="string"
     description="SMTP server hostname."
-    default="`smtp-relay.sendinblue.com`"
+    default="smtp-relay.sendinblue.com"
 />}}
 
 {{< configOption
     name="logger.smtp.username"
     type="string"
     description="Username for SMTP server authentication."
-    default="`admin@opentermsarchive.org`"
+    default="admin@opentermsarchive.org"
 />}}
 
 {{< configOption
     name="logger.sendMailOnError.to"
     type="string"
     description="Email address for error notifications."
-    example="`admin@example.com`"
+    example="admin@example.com"
 />}}
 
 {{< configOption
     name="logger.sendMailOnError.from"
     type="string"
     description="Sender email address for error notifications."
-    example="`noreply@example.com`"
+    example="noreply@example.com"
 />}}
 
 {{< configOption
     name="logger.sendMailOnError.sendWarnings"
     type="boolean"
     description="Set to true to also send email in case of warning."
-    default="`false`"
+    default="false"
 />}}
 
 {{< configOption
     name="logger.timestampPrefix"
     type="boolean"
     description="Set to false to avoid duplicate timestamps if logs are managed by a process manager."
-    default="`true`"
+    default="true"
 />}}
 
 ### Reporter
@@ -139,43 +139,43 @@ The reporter section manages how issues are reported when terms content is inacc
     name="reporter.type"
     type="string"
     description="Type of reporter"
-    example="`github`"
-    allowedValues="`github`, `gitlab`"
+    example="github"
+    allowedValues="github, gitlab"
 />}}
 
 {{< configOption
     name="reporter.repositories.declarations"
     type="string"
     description="Repository for creating issues."
-    example="`OpenTermsArchive/demo-declarations`"
+    example="OpenTermsArchive/demo-declarations"
 />}}
 
 {{< configOption
     name="reporter.repositories.versions"
     type="string"
     description="Repository for versions."
-    example="`OpenTermsArchive/demo-versions`"
+    example="OpenTermsArchive/demo-versions"
 />}}
 
 {{< configOption
     name="reporter.repositories.snapshots"
     type="string"
     description="Repository for snapshots."
-    example="`OpenTermsArchive/demo-snapshots`"
+    example="OpenTermsArchive/demo-snapshots"
 />}}
 
 {{< configOption
     name="reporter.baseURL"
     type="string"
     description="Base URL for GitLab (if applicable)."
-    example="`https://gitlab.example.com`"
+    example="https://gitlab.example.com"
 />}}
 
 {{< configOption
     name="reporter.apiBaseURL"
     type="string"
     description="API base URL for GitLab (if applicable)."
-    example="`https://api.gitlab.example.com`"
+    example="https://api.gitlab.example.com"
 />}}
 
 ### Dataset
@@ -186,21 +186,21 @@ The dataset section configures how datasets are published.
     name="dataset.title"
     type="string"
     description="Title of the dataset."
-    default="`sandbox`"
+    default="sandbox"
 />}}
 
 {{< configOption
     name="dataset.versionsRepositoryURL"
     type="string"
     description="Repository URL for dataset releases."
-    default="`https://github.com/OpenTermsArchive/sandbox`"
+    default="https://github.com/OpenTermsArchive/sandbox"
 />}}
 
 {{< configOption
     name="dataset.publishingSchedule"
     type="string"
-    description="Cron expression for dataset publishing."
-    default="`30 8 * * MON` (runs every Monday at 8:30 AM)"
+    description="Cron expression for dataset publishing. By default, it runs every Monday at 8:30 AM."
+    default="30 8 * * MON"
 />}}
 
 ### Collection API
@@ -211,7 +211,7 @@ The collection API section sets the parameters for the API server.
     name="collection-api.api.port"
     type="number"
     description="Port number for the API server."
-    example="`8080`"
+    example="8080"
     required=true
 />}}
 
@@ -219,7 +219,7 @@ The collection API section sets the parameters for the API server.
     name="collection-api.api.basePath"
     type="string"
     description="Base path for API endpoints."
-    example="`/collection-api`"
+    example="/collection-api"
     required=true
 />}}
 
@@ -233,8 +233,8 @@ The storage repositories section set the parameters for supported backends for s
     name="storage.type"
     type="string"
     description="Type of storage backend."
-    default="`git`"
-    allowedValues="`git`, `mongo`"
+    default="git"
+    allowedValues="git, mongo"
 />}}
 
 ### Git
@@ -245,35 +245,35 @@ The Git storage configuration allows to store versions in a Git repository.
     name="storage.git.path"
     type="string"
     description="Path to the versions database directory."
-    default="`./data/versions`"
+    default="./data/versions"
 />}}
 
 {{< configOption
     name="storage.git.publish"
     type="boolean"
     description="Boolean to push changes to the origin."
-    default="`false`"
+    default="false"
 />}}
 
 {{< configOption
     name="storage.git.snapshotIdentiferTemplate"
     type="string"
     description="Template for snapshot ID reference. `%SNAPSHOT_ID` will be replaced with the actual snapshot ID."
-    default="`./data/snapshots/%SNAPSHOT_ID`"
+    default="./data/snapshots/%SNAPSHOT_ID"
 />}}
 
 {{< configOption
     name="storage.git.author.name"
     type="string"
     description="Author name for changes."
-    default="`Open Terms Archive Bot`"
+    default="Open Terms Archive Bot"
 />}}
 
 {{< configOption
     name="storage.git.author.email"
     type="string"
     description="Author email for changes."
-    default="`bot@opentermsarchive.org`"
+    default="bot@opentermsarchive.org"
 />}}
 
 ### MongoDB
@@ -284,19 +284,19 @@ The MongoDB storage configuration allows to store versions in a MongoDB database
     name="storage.mongo.connectionURI"
     type="string"
     description="MongoDB connection URI."
-    default="`mongodb://127.0.0.1:27017`"
+    default="mongodb://127.0.0.1:27017"
 />}}
 
 {{< configOption
     name="storage.mongo.database"
     type="string"
     description="Database name."
-    default="`open-terms-archive`"
+    default="open-terms-archive"
 />}}
 
 {{< configOption
     name="storage.mongo.collection"
     type="string"
     description="Collection name."
-    default="`snapshots`"
+    default="snapshots"
 />}}
diff --git a/content/collections/references/metadata.md b/content/collections/references/metadata.md
index 3a3a765f..d6938ced 100644
--- a/content/collections/references/metadata.md
+++ b/content/collections/references/metadata.md
@@ -208,7 +208,7 @@ fr:
     name="roles"
     type="array of strings"
     description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/references/governance/)"
-    allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`"
+    allowedValues="host, administrator, curator, maintainer, sponsor"
     example="[host, administrator]"
     required=true
 />}}
diff --git a/themes/opentermsarchive/layouts/shortcodes/configOption.html b/themes/opentermsarchive/layouts/shortcodes/configOption.html
index 3d47810b..87954c9d 100644
--- a/themes/opentermsarchive/layouts/shortcodes/configOption.html
+++ b/themes/opentermsarchive/layouts/shortcodes/configOption.html
@@ -3,6 +3,7 @@
 {{ $required := .Get "required" }}
 {{ $allowedValues := .Get "allowedValues" }}
 {{ $default := .Get "default" }}
+{{ $reference := .Get "reference" }}
 {{/* Get description either from attribute or nested content */}}
 {{ $description := .Get "description" }}
 {{ $example := .Get "example" }}
@@ -20,7 +21,10 @@
     </div>
     <div class="config-option-details config-option-details__{{ if .Inner }}full{{ end }}">
         {{ if $default }}
-        <div class="config-option-default"><span>Default:</span>{{ $default | markdownify}}</div>
+            <div class="config-option-default">
+                <span>Default:</span>
+                <code>{{ $default | markdownify }}</code>
+            </div>
         {{ end }}
         {{ if or $example .Inner }}
         <div class="config-option-example"><span>Example:</span>
@@ -32,7 +36,14 @@
         </div>
         {{ end }}
         {{ if $allowedValues }}
-        <div class="config-option-allowed-values"><span>Allowed values:</span><span class="config-option-allowed-values-list">{{ $allowedValues | markdownify }}</span></div>
+            {{ $values := split $allowedValues "," }}
+            <div class="config-option-allowed-values"><span>Allowed values:</span>
+                <span class="config-option-allowed-values-list">
+                    {{ range $values }}
+                        <code>{{ . | markdownify }}</code>
+                    {{ end }}
+                </span>
+            </div>
         {{ end }}
     </div>
 </div>

From 27f4453d91e299f0a2397aaa48889b4ccbdf56c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 15:34:38 +0200
Subject: [PATCH 14/20] Add reference to config option

---
 content/terms/references/declaration.md                |  5 ++---
 .../assets/css/components/configOption.css             | 10 ++++++++--
 .../layouts/shortcodes/configOption.html               |  3 +++
 3 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/content/terms/references/declaration.md b/content/terms/references/declaration.md
index da4e5ea1..4848ad3c 100644
--- a/content/terms/references/declaration.md
+++ b/content/terms/references/declaration.md
@@ -26,10 +26,9 @@ The examples given throughout this reference can be seen in context in the [decl
 
 To facilitate cross-service comparisons and ensure consistency, a standardized list of term types is maintained in a [dedicated repository](https://github.com/OpenTermsArchive/terms-types).
 
-Please note, the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”.
-    `
+Please note, the terms type may differ from the exact name provided by the service, but it should align with the underlying commitment. For example, some providers might call “Terms and Conditions” or “Terms of Use” what some others call “Terms of Service”.`
     required=true
-    allowedValues="See the [terms-types repository](https://github.com/OpenTermsArchive/terms-types)."
+    reference="[Terms Types](https://github.com/OpenTermsArchive/terms-types)."
 >}}
 ```json
 "terms": {
diff --git a/themes/opentermsarchive/assets/css/components/configOption.css b/themes/opentermsarchive/assets/css/components/configOption.css
index a158d06c..de19b157 100644
--- a/themes/opentermsarchive/assets/css/components/configOption.css
+++ b/themes/opentermsarchive/assets/css/components/configOption.css
@@ -38,7 +38,8 @@
 .config-option-description,
 .config-option-default,
 .config-option-example,
-.config-option-allowed-values {
+.config-option-allowed-values,
+.config-option-reference {
   padding: 1rem 0.4em;
 }
 
@@ -51,7 +52,8 @@
 
 .config-option-example,
 .config-option-default,
-.config-option-allowed-values {
+.config-option-allowed-values,
+.config-option-reference {
   font-size: 0.85em;
 }
 
@@ -63,3 +65,7 @@
 .config-option-details_full .config-option-example .highlight {
   margin-top: 0.4em;
 }
+
+.config-option-reference span{
+  margin-right: 0.4em;
+}
diff --git a/themes/opentermsarchive/layouts/shortcodes/configOption.html b/themes/opentermsarchive/layouts/shortcodes/configOption.html
index 87954c9d..a62dc345 100644
--- a/themes/opentermsarchive/layouts/shortcodes/configOption.html
+++ b/themes/opentermsarchive/layouts/shortcodes/configOption.html
@@ -45,6 +45,9 @@
                 </span>
             </div>
         {{ end }}
+        {{ if $reference }}
+            <div class="config-option-reference"><span>Reference:</span>{{ $reference | markdownify }}</div>
+        {{ end }}
     </div>
 </div>
 

From 0386a32b0a513906336f96f0447d50cc7e6e9926 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 15:48:57 +0200
Subject: [PATCH 15/20] Improve naming

---
 content/api/cli.md                            | 32 ++++-----
 .../collections/references/configuration.md   | 70 +++++++++---------
 .../references/environment-variables.md       | 12 ++--
 content/collections/references/metadata.md    | 48 ++++++-------
 content/terms/references/declaration.md       | 32 ++++-----
 .../assets/css/components/configOption.css    | 71 -------------------
 .../assets/css/components/refItem.css         | 71 +++++++++++++++++++
 themes/opentermsarchive/assets/css/loader.css |  2 +-
 .../layouts/shortcodes/configOption.html      | 53 --------------
 .../layouts/shortcodes/refItem.html           | 51 +++++++++++++
 10 files changed, 220 insertions(+), 222 deletions(-)
 delete mode 100644 themes/opentermsarchive/assets/css/components/configOption.css
 create mode 100644 themes/opentermsarchive/assets/css/components/refItem.css
 delete mode 100644 themes/opentermsarchive/layouts/shortcodes/configOption.html
 create mode 100644 themes/opentermsarchive/layouts/shortcodes/refItem.html

diff --git a/content/api/cli.md b/content/api/cli.md
index bd0eef03..156165da 100644
--- a/content/api/cli.md
+++ b/content/api/cli.md
@@ -14,50 +14,50 @@ In these commands:
 
 ## Tracking terms
 
-{{< configOption name="ota track" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="npx ota track" />}}
+{{< refItem name="ota track" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="npx ota track" />}}
 
 > Note that the snapshots and versions will be recorded at the moment the command is executed, on top of the existing local history. If a shared history already exists and the goal is to add on top of it, that history has to be downloaded before executing that command.
 
-{{< configOption name="ota track --help" description="Show help and available options for track command" example="npx ota track --help" />}}
+{{< refItem name="ota track --help" description="Show help and available options for track command" example="npx ota track --help" />}}
 
-{{< configOption name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="npx ota track --services \"Facebook\" \"LinkedIn\"" />}}
+{{< refItem name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="npx ota track --services \"Facebook\" \"LinkedIn\"" />}}
 
-{{< configOption name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
+{{< refItem name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
 
-{{< configOption name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="npx ota track --schedule" />}}
+{{< refItem name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="npx ota track --schedule" />}}
 
 ## Validating declarations
 
-{{< configOption name="ota validate [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
+{{< refItem name="ota validate [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
 
-{{< configOption name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
+{{< refItem name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}}
 
-{{< configOption name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="npx ota validate --modified" />}}
+{{< refItem name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="npx ota validate --modified" />}}
 
 ## Linting declarations
 
-{{< configOption name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="npx ota lint --services \"Facebook\" \"LinkedIn\"" />}}
+{{< refItem name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="npx ota lint --services \"Facebook\" \"LinkedIn\"" />}}
 
-{{< configOption name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="npx ota lint --fix" />}}
+{{< refItem name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="npx ota lint --fix" />}}
 
-{{< configOption name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="npx ota lint --modified" />}}
+{{< refItem name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="npx ota lint --modified" />}}
 
 ## Publishing dataset
 
-{{< configOption name="ota dataset [--file <filename>]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="npx ota dataset --file dataset.zip" />}}
+{{< refItem name="ota dataset [--file <filename>]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="npx ota dataset --file dataset.zip" />}}
 
 To export the dataset into a ZIP file and publish it on GitHub releases:
 
-{{< configOption name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish" />}}
+{{< refItem name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish" />}}
 
 The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/references/environment-variables" >}}).
 
 To export, publish the dataset and remove the local copy that was created after it has been uploaded:
 
-{{< configOption name="ota dataset --publish --remove-local-copy [--file <filename>]" description="Export, publish dataset and remove local copy after upload" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy" />}}
+{{< refItem name="ota dataset --publish --remove-local-copy [--file <filename>]" description="Export, publish dataset and remove local copy after upload" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy" />}}
 
-{{< configOption name="ota dataset --schedule [--file <filename>]" description="Schedule export, publishing and local copy removal" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy" />}}
+{{< refItem name="ota dataset --schedule [--file <filename>]" description="Schedule export, publishing and local copy removal" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy" />}}
 
 ## Exposing the collection API
 
-{{< configOption name="ota serve" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="npx ota serve" />}}
+{{< refItem name="ota serve" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="npx ota serve" />}}
diff --git a/content/collections/references/configuration.md b/content/collections/references/configuration.md
index a08aad23..e5be913b 100644
--- a/content/collections/references/configuration.md
+++ b/content/collections/references/configuration.md
@@ -11,14 +11,14 @@ As an example, see the [production configuration file](https://github.com/OpenTe
 
 ## Options
 
-{{< configOption
+{{< refItem
     name="trackingSchedule"
     type="string"
     description="Defines how often the engine should check for changes in terms. Uses standard cron syntax to set the schedule. By default, it runs every 12 hours at minute 30."
     default="30 */12 * * *"
 />}}
 
-{{< configOption
+{{< refItem
     name="collectionPath"
     type="string"
     description="Path to the collection's directory containing declarations directory and metadata file, relative to the engine execution location"
@@ -30,13 +30,13 @@ As an example, see the [production configuration file](https://github.com/OpenTe
 
 The recorder section manages how versions and snapshots of terms are stored, supporting multiple storage backends.
 
-{{< configOption
+{{< refItem
     name="recorder.versions.storage"
     type="object"
     description="Configuration for storing versions. Supports Git and MongoDB. See [Storage Repositories](#storage-repositories) for more information."
 />}}
 
-{{< configOption
+{{< refItem
     name="recorder.snapshots.storage"
     type="object"
     description="Configuration for storing snapshots. Supports Git and MongoDB. See [Storage Repositories](#storage-repositories) for more information."
@@ -46,21 +46,21 @@ The recorder section manages how versions and snapshots of terms are stored, sup
 
 The fetcher section configures how the engine retrieves documents from the web.
 
-{{< configOption
+{{< refItem
     name="fetcher.waitForElementsTimeout"
     type="number"
     description="Maximum wait time for elements to appear in a page (milliseconds)."
     default="10000"
 />}}
 
-{{< configOption
+{{< refItem
     name="fetcher.navigationTimeout"
     type="number"
     description="Maximum wait time for a page to load (milliseconds)."
     default="30000"
 />}}
 
-{{< configOption
+{{< refItem
     name="fetcher.language"
     type="string"
     description="Language code (ISO 639-1) for request headers."
@@ -71,14 +71,14 @@ The fetcher section configures how the engine retrieves documents from the web.
 
 The notifier section sets up how notifications are sent when new versions of terms are recorded.
 
-{{< configOption
+{{< refItem
     name="notifier.sendInBlue.updatesListId"
     type="string"
     description="SendInBlue contacts list ID of persons to notify on terms updates."
     default="850"
 />}}
 
-{{< configOption
+{{< refItem
     name="notifier.sendInBlue.updateTemplateId"
     type="string"
     description="SendInBlue email template ID used for updates notifications."
@@ -89,42 +89,42 @@ The notifier section sets up how notifications are sent when new versions of ter
 
 The logger section configures logging and error notification settings.
 
-{{< configOption
+{{< refItem
     name="logger.smtp.host"
     type="string"
     description="SMTP server hostname."
     default="smtp-relay.sendinblue.com"
 />}}
 
-{{< configOption
+{{< refItem
     name="logger.smtp.username"
     type="string"
     description="Username for SMTP server authentication."
     default="admin@opentermsarchive.org"
 />}}
 
-{{< configOption
+{{< refItem
     name="logger.sendMailOnError.to"
     type="string"
     description="Email address for error notifications."
     example="admin@example.com"
 />}}
 
-{{< configOption
+{{< refItem
     name="logger.sendMailOnError.from"
     type="string"
     description="Sender email address for error notifications."
     example="noreply@example.com"
 />}}
 
-{{< configOption
+{{< refItem
     name="logger.sendMailOnError.sendWarnings"
     type="boolean"
     description="Set to true to also send email in case of warning."
     default="false"
 />}}
 
-{{< configOption
+{{< refItem
     name="logger.timestampPrefix"
     type="boolean"
     description="Set to false to avoid duplicate timestamps if logs are managed by a process manager."
@@ -135,7 +135,7 @@ The logger section configures logging and error notification settings.
 
 The reporter section manages how issues are reported when terms content is inaccessible, supporting GitHub and GitLab.
 
-{{< configOption
+{{< refItem
     name="reporter.type"
     type="string"
     description="Type of reporter"
@@ -143,35 +143,35 @@ The reporter section manages how issues are reported when terms content is inacc
     allowedValues="github, gitlab"
 />}}
 
-{{< configOption
+{{< refItem
     name="reporter.repositories.declarations"
     type="string"
     description="Repository for creating issues."
     example="OpenTermsArchive/demo-declarations"
 />}}
 
-{{< configOption
+{{< refItem
     name="reporter.repositories.versions"
     type="string"
     description="Repository for versions."
     example="OpenTermsArchive/demo-versions"
 />}}
 
-{{< configOption
+{{< refItem
     name="reporter.repositories.snapshots"
     type="string"
     description="Repository for snapshots."
     example="OpenTermsArchive/demo-snapshots"
 />}}
 
-{{< configOption
+{{< refItem
     name="reporter.baseURL"
     type="string"
     description="Base URL for GitLab (if applicable)."
     example="https://gitlab.example.com"
 />}}
 
-{{< configOption
+{{< refItem
     name="reporter.apiBaseURL"
     type="string"
     description="API base URL for GitLab (if applicable)."
@@ -182,21 +182,21 @@ The reporter section manages how issues are reported when terms content is inacc
 
 The dataset section configures how datasets are published.
 
-{{< configOption
+{{< refItem
     name="dataset.title"
     type="string"
     description="Title of the dataset."
     default="sandbox"
 />}}
 
-{{< configOption
+{{< refItem
     name="dataset.versionsRepositoryURL"
     type="string"
     description="Repository URL for dataset releases."
     default="https://github.com/OpenTermsArchive/sandbox"
 />}}
 
-{{< configOption
+{{< refItem
     name="dataset.publishingSchedule"
     type="string"
     description="Cron expression for dataset publishing. By default, it runs every Monday at 8:30 AM."
@@ -207,7 +207,7 @@ The dataset section configures how datasets are published.
 
 The collection API section sets the parameters for the API server.
 
-{{< configOption
+{{< refItem
     name="collection-api.api.port"
     type="number"
     description="Port number for the API server."
@@ -215,7 +215,7 @@ The collection API section sets the parameters for the API server.
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="collection-api.api.basePath"
     type="string"
     description="Base path for API endpoints."
@@ -229,7 +229,7 @@ The collection API section sets the parameters for the API server.
 
 The storage repositories section set the parameters for supported backends for storing versions and snapshots, supporting Git and MongoDB.
 
-{{< configOption
+{{< refItem
     name="storage.type"
     type="string"
     description="Type of storage backend."
@@ -241,35 +241,35 @@ The storage repositories section set the parameters for supported backends for s
 
 The Git storage configuration allows to store versions in a Git repository.
 
-{{< configOption
+{{< refItem
     name="storage.git.path"
     type="string"
     description="Path to the versions database directory."
     default="./data/versions"
 />}}
 
-{{< configOption
+{{< refItem
     name="storage.git.publish"
     type="boolean"
     description="Boolean to push changes to the origin."
     default="false"
 />}}
 
-{{< configOption
+{{< refItem
     name="storage.git.snapshotIdentiferTemplate"
     type="string"
     description="Template for snapshot ID reference. `%SNAPSHOT_ID` will be replaced with the actual snapshot ID."
     default="./data/snapshots/%SNAPSHOT_ID"
 />}}
 
-{{< configOption
+{{< refItem
     name="storage.git.author.name"
     type="string"
     description="Author name for changes."
     default="Open Terms Archive Bot"
 />}}
 
-{{< configOption
+{{< refItem
     name="storage.git.author.email"
     type="string"
     description="Author email for changes."
@@ -280,21 +280,21 @@ The Git storage configuration allows to store versions in a Git repository.
 
 The MongoDB storage configuration allows to store versions in a MongoDB database.
 
-{{< configOption
+{{< refItem
     name="storage.mongo.connectionURI"
     type="string"
     description="MongoDB connection URI."
     default="mongodb://127.0.0.1:27017"
 />}}
 
-{{< configOption
+{{< refItem
     name="storage.mongo.database"
     type="string"
     description="Database name."
     default="open-terms-archive"
 />}}
 
-{{< configOption
+{{< refItem
     name="storage.mongo.collection"
     type="string"
     description="Collection name."
diff --git a/content/collections/references/environment-variables.md b/content/collections/references/environment-variables.md
index de02430f..c17178bc 100644
--- a/content/collections/references/environment-variables.md
+++ b/content/collections/references/environment-variables.md
@@ -9,18 +9,18 @@ This reference documentation details all available environment variables that ca
 
 ### Engine
 
-{{< configOption name="OTA_ENGINE_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." />}}
+{{< refItem name="OTA_ENGINE_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." />}}
 
-{{< configOption name="OTA_ENGINE_SENDINBLUE_API_KEY" type="string" description="API key for SendInBlue." />}}
+{{< refItem name="OTA_ENGINE_SENDINBLUE_API_KEY" type="string" description="API key for SendInBlue." />}}
 
-{{< configOption name="OTA_ENGINE_GITHUB_TOKEN" type="string" description="GitHub token for API access." />}}
+{{< refItem name="OTA_ENGINE_GITHUB_TOKEN" type="string" description="GitHub token for API access." />}}
 
-{{< configOption name="OTA_ENGINE_GITLAB_TOKEN" type="string" description="GitLab token for API access." />}}
+{{< refItem name="OTA_ENGINE_GITLAB_TOKEN" type="string" description="GitLab token for API access." />}}
 
-{{< configOption name="OTA_ENGINE_GITLAB_RELEASES_TOKEN" type="string" description="GitLab token for dataset releases." />}}
+{{< refItem name="OTA_ENGINE_GITLAB_RELEASES_TOKEN" type="string" description="GitLab token for dataset releases." />}}
 
 ---
 
 ### Federation API 
 
-{{< configOption name="OTA_FEDERATION_API_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." />}}
+{{< refItem name="OTA_FEDERATION_API_SMTP_PASSWORD" type="string" description="SMTP password for email error notifications." />}}
diff --git a/content/collections/references/metadata.md b/content/collections/references/metadata.md
index d6938ced..06a1191d 100644
--- a/content/collections/references/metadata.md
+++ b/content/collections/references/metadata.md
@@ -13,7 +13,7 @@ The examples given throughout this reference can be seen in context in the [comp
 
 ## Fields
 
-{{< configOption
+{{< refItem
     name="id"
     type="string"
     description="Unique identifier derived from name (acronyms, dash-separated)."
@@ -21,7 +21,7 @@ The examples given throughout this reference can be seen in context in the [comp
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="name"
     type="string"
     description="Display name of the collection."
@@ -29,7 +29,7 @@ The examples given throughout this reference can be seen in context in the [comp
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="tagline"
     type="string"
     description="Concise description of collection topic."
@@ -37,7 +37,7 @@ The examples given throughout this reference can be seen in context in the [comp
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="languages"
     type="array of strings"
     description="List of [ISO 639-1 (two-letter)](https://en.wikipedia.org/wiki/ISO_639) language codes representing languages allowed in the collection."
@@ -45,7 +45,7 @@ The examples given throughout this reference can be seen in context in the [comp
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="jurisdictions"
     type="array of strings"
     description="List of [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) representing jurisdictions covered by the collection."
@@ -53,7 +53,7 @@ The examples given throughout this reference can be seen in context in the [comp
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="description"
     type="string"
     description="Detailed description of the collection"
@@ -66,9 +66,9 @@ description: >
 
     This provides a reference collection for best practices and enables the Open Terms Archive Core Team to be a user of the software it produces.
 ```
-{{< /configOption >}}
+{{< /refItem >}}
 
-{{< configOption
+{{< refItem
     name="dataset"
     type="uri"
     description="URL to the dataset releases."
@@ -76,7 +76,7 @@ description: >
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="declarations"
     type="uri"
     description="URL to the declarations repository."
@@ -84,7 +84,7 @@ description: >
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="versions"
     type="uri"
     description="URL to the versions repository."
@@ -92,7 +92,7 @@ description: >
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="snapshots"
     type="uri"
     description="URL to the snapshots repository."
@@ -100,7 +100,7 @@ description: >
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="donations"
     type="uri"
     description="URL to the donations page."
@@ -108,7 +108,7 @@ description: >
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="logo"
     type="uri"
     description="URL to the collection's logo. Optimized PNG transparent image (minimum width 240px)."
@@ -116,21 +116,21 @@ description: >
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="trackingPeriods"
     type="array of objects"
     description="List of time periods during which terms were tracked, with their tracking configuration. Gaps between periods indicate times when tracking was interrupted. See [TrackingPeriods]({{< relref \"#trackingperiods\" >}}) section."
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="governance"
     type="object of objects"
     description="Map of organizations involved in the collection's governance, with organization names as keys and governance objects as values. See [Governance]({{< relref \"#governance\" >}}) section."
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="i18n"
     type="object of objects"
     description="Internationalization of any of the Metadata properties (except i18n itself) for different language codes"
@@ -145,13 +145,13 @@ fr:
         name: Ministère de l'Europe et des Affaires étrangères
         url: https://www.diplomatie.gouv.fr
 ```
-{{< /configOption >}}
+{{< /refItem >}}
 
 ---
 
 ### TrackingPeriods
 
-{{< configOption
+{{< refItem
     name="startDate"
     type="date"
     description="The date when tracking started for this period (ISO 8601 format YYYY-MM-DD)."
@@ -159,7 +159,7 @@ fr:
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="schedule"
     type="cron-expression"
     description="A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency."
@@ -167,7 +167,7 @@ fr:
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="serverLocation"
     type="string"
     description="The geographic location of the tracking server (city name and ISO 3166-2 country code)."
@@ -175,7 +175,7 @@ fr:
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="endDate"
     type="date"
     description="The date when tracking ended for this period (ISO 8601 format YYYY-MM-DD). If not specified, tracking is ongoing."
@@ -188,7 +188,7 @@ fr:
 
 ### Governance
 
-{{< configOption
+{{< refItem
     name="url"
     type="uri"
     description="URL to the entity's website"
@@ -196,7 +196,7 @@ fr:
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="logo"
     type="uri"
     description="URL to the entity's logo. Optimized PNG transparent image (minimum width 240px)."
@@ -204,7 +204,7 @@ fr:
     required=false
 />}}
 
-{{< configOption
+{{< refItem
     name="roles"
     type="array of strings"
     description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/references/governance/)"
diff --git a/content/terms/references/declaration.md b/content/terms/references/declaration.md
index 4848ad3c..36962cc7 100644
--- a/content/terms/references/declaration.md
+++ b/content/terms/references/declaration.md
@@ -11,7 +11,7 @@ The examples given throughout this reference can be seen in context in the [decl
 
 ## Properties
 
-{{< configOption
+{{< refItem
     name="name"
     type="string"
     description="The name of the service."
@@ -19,7 +19,7 @@ The examples given throughout this reference can be seen in context in the [decl
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="terms"
     type="object of objects"
     description=`Map of terms associated with a service, where keys are standardized term types (e.g., "Privacy Policy", "Terms of Service"), and values are term objects containing the configuration for fetching and processing each document, as detailed in the [Terms declaration]({{< relref \"#terms-declaration\" >}}) section.
@@ -42,13 +42,13 @@ Please note, the terms type may differ from the exact name provided by the servi
     }
 }
 ```
-{{< /configOption >}}
+{{< /refItem >}}
 
 ---
 
 ### Terms declaration
 
-{{< configOption
+{{< refItem
     name="fetch"
     type="uri"
     description="The URL where the terms document can be downloaded."
@@ -56,7 +56,7 @@ Please note, the terms type may differ from the exact name provided by the servi
     required=true
 />}}
 
-{{< configOption
+{{< refItem
     name="select"
     type="string, object or array"
     description=`
@@ -90,9 +90,9 @@ As an array of those:
     }
 ]
 ```
-{{< /configOption >}}
+{{< /refItem >}}
 
-{{< configOption
+{{< refItem
     name="executeClientScripts"
     type="boolean"
     description=`Boolean flag to execute client-side JavaScript before accessing content.
@@ -102,7 +102,7 @@ When enabled, this loads the page in a headless browser to execute client-side s
     example="true"
 />}}
 
-{{< configOption
+{{< refItem
     name="remove"
     type="string, object or array"
     description=`
@@ -135,16 +135,16 @@ As an array of those:
     }
 ]
 ```
-{{< /configOption >}}
+{{< /refItem >}}
 
-{{< configOption
+{{< refItem
     name="filter"
     type="array of strings"
     description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"terms/references/filters\" >}}) section for more information."
     example="[\"filterName1\", \"filterName2\"]"
 />}}
 
-{{< configOption
+{{< refItem
     name="combine"
     type="array of objects"
     description=`
@@ -167,13 +167,13 @@ Common properties (can be a combination of "select", "remove", "filter" and "exe
     }
 ]
 ```
-{{< /configOption >}}
+{{< /refItem >}}
 
 ---
 
 ### Range selector
 
-{{< configOption
+{{< refItem
     name="startBefore"
     type="CSS selector"
     description="The CSS selector for the element before which the range starts."
@@ -181,7 +181,7 @@ Common properties (can be a combination of "select", "remove", "filter" and "exe
     required="either `startBefore` or `startAfter` is required"
 />}}
 
-{{< configOption
+{{< refItem
     name="startAfter"
     type="CSS selector"
     description="The CSS selector for the element after which the range starts."
@@ -189,7 +189,7 @@ Common properties (can be a combination of "select", "remove", "filter" and "exe
     required="either `startBefore` or `startAfter` is required"
 />}}
 
-{{< configOption
+{{< refItem
     name="endBefore"
     type="CSS selector"
     description="The CSS selector for the element before which the range ends."
@@ -197,7 +197,7 @@ Common properties (can be a combination of "select", "remove", "filter" and "exe
     required="either `endBefore` or `endAfter` is required"
 />}}
 
-{{< configOption
+{{< refItem
     name="endAfter"
     type="CSS selector"
     description="The CSS selector for the element after which the range ends."
diff --git a/themes/opentermsarchive/assets/css/components/configOption.css b/themes/opentermsarchive/assets/css/components/configOption.css
deleted file mode 100644
index de19b157..00000000
--- a/themes/opentermsarchive/assets/css/components/configOption.css
+++ /dev/null
@@ -1,71 +0,0 @@
-.config-option {
-    padding: 2rem 0;
-}
-
-.config-option + .config-option {
-  box-shadow: inset 0 1px var(--colorBlack200);
-}
-
-.config-option-name code {
-  font-weight: 600;
-  overflow-y: auto;
-  font-size: 1em;
-}
-
-.config-option-type {
-  color: var(--colorBlack600);
-  padding-left: 1rem;
-  text-transform: lowercase;
-}
-
-.config-option-required {
-  padding-left: 1rem;
-  color: rgb(154, 103, 0);
-}
-
-.config-option-required code {
-  font-weight: 400;
-}
-
-.config-option-details {
-  display: flex;
-}
-
-.config-option-details__full {
-  flex-direction: column;
-}
-
-.config-option-description,
-.config-option-default,
-.config-option-example,
-.config-option-allowed-values,
-.config-option-reference {
-  padding: 1rem 0.4em;
-}
-
-.config-option-example code,
-.config-option-default code,
-.config-option-allowed-values-list {
-  margin-left: 0.4em;
-  display: inline-block;
-}
-
-.config-option-example,
-.config-option-default,
-.config-option-allowed-values,
-.config-option-reference {
-  font-size: 0.85em;
-}
-
-.config-option-details_full .config-option-example {
-  overflow-y: auto;
-  width: 100%;
-}
-
-.config-option-details_full .config-option-example .highlight {
-  margin-top: 0.4em;
-}
-
-.config-option-reference span{
-  margin-right: 0.4em;
-}
diff --git a/themes/opentermsarchive/assets/css/components/refItem.css b/themes/opentermsarchive/assets/css/components/refItem.css
new file mode 100644
index 00000000..5c84ee57
--- /dev/null
+++ b/themes/opentermsarchive/assets/css/components/refItem.css
@@ -0,0 +1,71 @@
+.refItem {
+    padding: 2rem 0;
+}
+
+.refItem + .refItem {
+  box-shadow: inset 0 1px var(--colorBlack200);
+}
+
+.refItem-name code {
+  font-weight: 600;
+  overflow-y: auto;
+  font-size: 1em;
+}
+
+.refItem-type {
+  color: var(--colorBlack600);
+  padding-left: 1rem;
+  text-transform: lowercase;
+}
+
+.refItem-required {
+  padding-left: 1rem;
+  color: rgb(154, 103, 0);
+}
+
+.refItem-required code {
+  font-weight: 400;
+}
+
+.refItem-details {
+  display: flex;
+}
+
+.refItem-details__full {
+  flex-direction: column;
+}
+
+.refItem-description,
+.refItem-default,
+.refItem-example,
+.refItem-allowed-values,
+.refItem-reference {
+  padding: 1rem 0.4em;
+}
+
+.refItem-example code,
+.refItem-default code,
+.refItem-allowed-values-list {
+  margin-left: 0.4em;
+  display: inline-block;
+}
+
+.refItem-example,
+.refItem-default,
+.refItem-allowed-values,
+.refItem-reference {
+  font-size: 0.85em;
+}
+
+.refItem-details_full .refItem-example {
+  overflow-y: auto;
+  width: 100%;
+}
+
+.refItem-details_full .refItem-example .highlight {
+  margin-top: 0.4em;
+}
+
+.refItem-reference span{
+  margin-right: 0.4em;
+}
diff --git a/themes/opentermsarchive/assets/css/loader.css b/themes/opentermsarchive/assets/css/loader.css
index e5446ce1..49d9e6fe 100644
--- a/themes/opentermsarchive/assets/css/loader.css
+++ b/themes/opentermsarchive/assets/css/loader.css
@@ -35,4 +35,4 @@
 @import "/components/divider.css";
 @import "/components/textContent.css";
 @import "/components/aside.css";
-@import "/components/configOption.css";
+@import "/components/refItem.css";
diff --git a/themes/opentermsarchive/layouts/shortcodes/configOption.html b/themes/opentermsarchive/layouts/shortcodes/configOption.html
deleted file mode 100644
index a62dc345..00000000
--- a/themes/opentermsarchive/layouts/shortcodes/configOption.html
+++ /dev/null
@@ -1,53 +0,0 @@
-{{ $name := .Get "name" }}
-{{ $type := .Get "type" }}
-{{ $required := .Get "required" }}
-{{ $allowedValues := .Get "allowedValues" }}
-{{ $default := .Get "default" }}
-{{ $reference := .Get "reference" }}
-{{/* Get description either from attribute or nested content */}}
-{{ $description := .Get "description" }}
-{{ $example := .Get "example" }}
-
-<div class="config-option">
-    <div class="config-option-name">
-        <code>{{ $name }}</code>
-        <span class="config-option-type">{{ $type }}</span>
-        {{ with $required }}
-            <span class="config-option-required">{{ if eq . true }}required{{ else }}{{ . | markdownify }}{{ end }}</span>
-        {{ end }}
-    </div>
-    <div class="config-option-description">
-        {{ $description | markdownify | safeHTML }}
-    </div>
-    <div class="config-option-details config-option-details__{{ if .Inner }}full{{ end }}">
-        {{ if $default }}
-            <div class="config-option-default">
-                <span>Default:</span>
-                <code>{{ $default | markdownify }}</code>
-            </div>
-        {{ end }}
-        {{ if or $example .Inner }}
-        <div class="config-option-example"><span>Example:</span>
-            {{ if .Inner }}
-                {{ .Inner | markdownify }}
-            {{ else }}
-                <code>{{ $example | markdownify }}</code>
-            {{ end }}
-        </div>
-        {{ end }}
-        {{ if $allowedValues }}
-            {{ $values := split $allowedValues "," }}
-            <div class="config-option-allowed-values"><span>Allowed values:</span>
-                <span class="config-option-allowed-values-list">
-                    {{ range $values }}
-                        <code>{{ . | markdownify }}</code>
-                    {{ end }}
-                </span>
-            </div>
-        {{ end }}
-        {{ if $reference }}
-            <div class="config-option-reference"><span>Reference:</span>{{ $reference | markdownify }}</div>
-        {{ end }}
-    </div>
-</div>
-
diff --git a/themes/opentermsarchive/layouts/shortcodes/refItem.html b/themes/opentermsarchive/layouts/shortcodes/refItem.html
new file mode 100644
index 00000000..cfc58aaa
--- /dev/null
+++ b/themes/opentermsarchive/layouts/shortcodes/refItem.html
@@ -0,0 +1,51 @@
+{{ $name := .Get "name" }}
+{{ $type := .Get "type" }}
+{{ $required := .Get "required" }}
+{{ $allowedValues := .Get "allowedValues" }}
+{{ $default := .Get "default" }}
+{{ $reference := .Get "reference" }}
+{{/* Get description either from attribute or nested content */}}
+{{ $description := .Get "description" }}
+{{ $example := .Get "example" }}
+
+<div class="refItem">
+  <div class="refItem-name">
+    <code>{{ $name }}</code>
+    <span class="refItem-type">{{ $type }}</span>
+    {{ with $required }}
+      <span class="refItem-required">{{ if eq . true }}required{{ else }}{{ . | markdownify }}{{ end }}</span>
+    {{ end }}
+  </div>
+  <div class="refItem-description">{{ $description | markdownify | safeHTML }}</div>
+  <div class="refItem-details refItem-details__{{ if .Inner }}full{{ end }}">
+    {{ if $default }}
+      <div class="refItem-default">
+        <span>Default:</span>
+        <code>{{ $default | markdownify }}</code>
+      </div>
+    {{ end }}
+    {{ if or $example .Inner }}
+      <div class="refItem-example"><span>Example:</span>
+        {{ if .Inner }}
+          {{ .Inner | markdownify }}
+        {{ else }}
+          <code>{{ $example | markdownify }}</code>
+        {{ end }}
+      </div>
+    {{ end }}
+    {{ if $allowedValues }}
+      {{ $values := split $allowedValues "," }}
+      <div class="refItem-allowed-values"><span>Allowed values:</span>
+        <span class="refItem-allowed-values-list">
+          {{ range $values }}
+            <code>{{ . | markdownify }}</code>
+          {{ end }}
+        </span>
+      </div>
+    {{ end }}
+    {{ if $reference }}
+      <div class="refItem-reference"><span>Reference:</span>{{ $reference | markdownify }}</div>
+    {{ end }}
+  </div>
+</div>
+

From 7037872bb17218d4a775a3bcdbd57f0784e530f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 16:04:13 +0200
Subject: [PATCH 16/20] Do not render links

---
 themes/opentermsarchive/layouts/shortcodes/refItem.html | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/themes/opentermsarchive/layouts/shortcodes/refItem.html b/themes/opentermsarchive/layouts/shortcodes/refItem.html
index cfc58aaa..8bd96902 100644
--- a/themes/opentermsarchive/layouts/shortcodes/refItem.html
+++ b/themes/opentermsarchive/layouts/shortcodes/refItem.html
@@ -21,7 +21,7 @@
     {{ if $default }}
       <div class="refItem-default">
         <span>Default:</span>
-        <code>{{ $default | markdownify }}</code>
+        <code>{{ $default | markdownify | replaceRE "<a[^>]*>(.*?)</a>" "$1" | safeHTML }}</code>
       </div>
     {{ end }}
     {{ if or $example .Inner }}
@@ -29,7 +29,7 @@
         {{ if .Inner }}
           {{ .Inner | markdownify }}
         {{ else }}
-          <code>{{ $example | markdownify }}</code>
+          <code>{{ $example | markdownify | replaceRE "<a[^>]*>(.*?)</a>" "$1" | safeHTML }}</code>
         {{ end }}
       </div>
     {{ end }}
@@ -38,7 +38,7 @@
       <div class="refItem-allowed-values"><span>Allowed values:</span>
         <span class="refItem-allowed-values-list">
           {{ range $values }}
-            <code>{{ . | markdownify }}</code>
+            <code>{{ . | markdownify | replaceRE "<a[^>]*>(.*?)</a>" "$1" | safeHTML }}</code>
           {{ end }}
         </span>
       </div>

From 43d5a691c0078e55d23d48c86b6b47a1525486cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 16:04:13 +0200
Subject: [PATCH 17/20] Singularize slugs and pluralize menu titles sections

---
 .../{how-to-guides => how-to}/_index.md         |   0
 .../navigate-history.md                         |   1 -
 .../{how-to-guides => how-to}/publish-memo.md   |   1 -
 content/api/cli.md                              |   2 +-
 .../{how-to-guides => how-to}/_index.md         |   0
 .../create-repositories.md                      |   2 --
 .../{how-to-guides => how-to}/create.md         |   8 +++-----
 .../define-metadata.md                          |   2 --
 .../{references => reference}/_index.md         |   0
 .../{references => reference}/configuration.md  |   0
 .../environment-variables.md                    |   0
 .../{references => reference}/governance.md     |   0
 .../{references => reference}/metadata.md       |   0
 .../{tutorials => tutorial}/_index.md           |   0
 .../{tutorials => tutorial}/create.md           |   6 ++++--
 .../{how-to-guides => how-to}/_index.md         |   0
 .../join-community-chat.md                      |   1 -
 .../{how-to-guides => how-to}/_index.md         |   0
 .../{how-to-guides => how-to}/deploy.md         |   2 --
 .../setup-github-teams.md                       |   2 --
 .../{how-to-guides => how-to}/_index.md         |   0
 .../{how-to-guides => how-to}/join.md           |   2 --
 .../{references => reference}/_index.md         |   0
 .../{references => reference}/criteria.md       |   6 +++---
 .../{explanations => explanation}/_index.md     |   0
 .../declarations-maintenance.md                 |   0
 .../range-selectors.md                          |   0
 content/terms/guideline/_index.md               |   4 ++++
 .../choosing-selectors.md                       |   8 +++++---
 .../{guidelines => guideline}/declaring.md      |   4 +++-
 .../{guidelines => guideline}/reviewing.md      |  16 +++++++++-------
 .../{guidelines => guideline}/targeting.md      |   3 ++-
 content/terms/guidelines/_index.md              |   4 ----
 .../terms/{how-to-guides => how-to}/_index.md   |   0
 .../add-terms-using-UI.md                       |   1 -
 .../{how-to-guides => how-to}/be-notified.md    |   3 +--
 ...-maintenance-inspector-open-get-datetime.png | Bin
 ...s-maintenance-ota-bot-comment-last-month.png | Bin
 ...intenance-ota-bot-comment-reopened-issue.png | Bin
 ...declarations-maintenance-ota-bot-comment.png | Bin
 .../get-the-validUntil-date-from-an-issue.md    |   2 --
 .../rename-a-service.md                         |   4 +---
 .../terminate-a-service.md                      |   2 --
 .../test-declaration.md                         |   0
 .../track-new-terms.md                          |   7 +++----
 .../terms/{references => reference}/_index.md   |   0
 .../{references => reference}/declaration.md    |   4 ++--
 .../terms/{references => reference}/filters.md  |   2 +-
 content/terms/{tutorials => tutorial}/_index.md |   0
 content/terms/{tutorials => tutorial}/track.md  |   2 ++
 50 files changed, 44 insertions(+), 57 deletions(-)
 rename content/analysis/{how-to-guides => how-to}/_index.md (100%)
 rename content/analysis/{how-to-guides => how-to}/navigate-history.md (99%)
 rename content/analysis/{how-to-guides => how-to}/publish-memo.md (98%)
 rename content/collections/{how-to-guides => how-to}/_index.md (100%)
 rename content/collections/{how-to-guides => how-to}/create-repositories.md (98%)
 rename content/collections/{how-to-guides => how-to}/create.md (82%)
 rename content/collections/{how-to-guides => how-to}/define-metadata.md (98%)
 rename content/collections/{references => reference}/_index.md (100%)
 rename content/collections/{references => reference}/configuration.md (100%)
 rename content/collections/{references => reference}/environment-variables.md (100%)
 rename content/collections/{references => reference}/governance.md (100%)
 rename content/collections/{references => reference}/metadata.md (100%)
 rename content/collections/{tutorials => tutorial}/_index.md (100%)
 rename content/collections/{tutorials => tutorial}/create.md (96%)
 rename content/community/{how-to-guides => how-to}/_index.md (100%)
 rename content/community/{how-to-guides => how-to}/join-community-chat.md (98%)
 rename content/deployment/{how-to-guides => how-to}/_index.md (100%)
 rename content/deployment/{how-to-guides => how-to}/deploy.md (99%)
 rename content/deployment/{how-to-guides => how-to}/setup-github-teams.md (97%)
 rename content/federation/{how-to-guides => how-to}/_index.md (100%)
 rename content/federation/{how-to-guides => how-to}/join.md (95%)
 rename content/federation/{references => reference}/_index.md (100%)
 rename content/federation/{references => reference}/criteria.md (95%)
 rename content/terms/{explanations => explanation}/_index.md (100%)
 rename content/terms/{explanations => explanation}/declarations-maintenance.md (100%)
 rename content/terms/{explanations => explanation}/range-selectors.md (100%)
 create mode 100644 content/terms/guideline/_index.md
 rename content/terms/{guidelines => guideline}/choosing-selectors.md (92%)
 rename content/terms/{guidelines => guideline}/declaring.md (99%)
 rename content/terms/{guidelines => guideline}/reviewing.md (95%)
 rename content/terms/{guidelines => guideline}/targeting.md (87%)
 delete mode 100644 content/terms/guidelines/_index.md
 rename content/terms/{how-to-guides => how-to}/_index.md (100%)
 rename content/terms/{how-to-guides => how-to}/add-terms-using-UI.md (96%)
 rename content/terms/{how-to-guides => how-to}/be-notified.md (92%)
 rename content/terms/{how-to-guides => how-to}/declarations-maintenance-inspector-open-get-datetime.png (100%)
 rename content/terms/{how-to-guides => how-to}/declarations-maintenance-ota-bot-comment-last-month.png (100%)
 rename content/terms/{how-to-guides => how-to}/declarations-maintenance-ota-bot-comment-reopened-issue.png (100%)
 rename content/terms/{how-to-guides => how-to}/declarations-maintenance-ota-bot-comment.png (100%)
 rename content/terms/{how-to-guides => how-to}/get-the-validUntil-date-from-an-issue.md (93%)
 rename content/terms/{how-to-guides => how-to}/rename-a-service.md (50%)
 rename content/terms/{how-to-guides => how-to}/terminate-a-service.md (93%)
 rename content/terms/{how-to-guides => how-to}/test-declaration.md (100%)
 rename content/terms/{how-to-guides => how-to}/track-new-terms.md (91%)
 rename content/terms/{references => reference}/_index.md (100%)
 rename content/terms/{references => reference}/declaration.md (98%)
 rename content/terms/{references => reference}/filters.md (97%)
 rename content/terms/{tutorials => tutorial}/_index.md (100%)
 rename content/terms/{tutorials => tutorial}/track.md (98%)

diff --git a/content/analysis/how-to-guides/_index.md b/content/analysis/how-to/_index.md
similarity index 100%
rename from content/analysis/how-to-guides/_index.md
rename to content/analysis/how-to/_index.md
diff --git a/content/analysis/how-to-guides/navigate-history.md b/content/analysis/how-to/navigate-history.md
similarity index 99%
rename from content/analysis/how-to-guides/navigate-history.md
rename to content/analysis/how-to/navigate-history.md
index 9b47b218..350cb88b 100644
--- a/content/analysis/how-to-guides/navigate-history.md
+++ b/content/analysis/how-to/navigate-history.md
@@ -4,7 +4,6 @@ weight: 1
 aliases:
   - /navigate-history/
   - /terms/how-to-navigate-history/
-  - /analysis/how-to/navigate-history/
 ---
 
 # How to navigate history
diff --git a/content/analysis/how-to-guides/publish-memo.md b/content/analysis/how-to/publish-memo.md
similarity index 98%
rename from content/analysis/how-to-guides/publish-memo.md
rename to content/analysis/how-to/publish-memo.md
index 0246fcf0..18699bdb 100644
--- a/content/analysis/how-to-guides/publish-memo.md
+++ b/content/analysis/how-to/publish-memo.md
@@ -2,7 +2,6 @@
 title: Publish a memo
 aliases: 
   - /memos/how-to-publish/
-  - /analysis/how-to/publish-memo/
 ---
 
 # How to publish a memo
diff --git a/content/api/cli.md b/content/api/cli.md
index 156165da..8acb8beb 100644
--- a/content/api/cli.md
+++ b/content/api/cli.md
@@ -50,7 +50,7 @@ To export the dataset into a ZIP file and publish it on GitHub releases:
 
 {{< refItem name="ota dataset --publish [--file <filename>]" description="Export and publish dataset to GitHub releases" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish" />}}
 
-The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/references/environment-variables" >}}).
+The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/reference/environment-variables" >}}).
 
 To export, publish the dataset and remove the local copy that was created after it has been uploaded:
 
diff --git a/content/collections/how-to-guides/_index.md b/content/collections/how-to/_index.md
similarity index 100%
rename from content/collections/how-to-guides/_index.md
rename to content/collections/how-to/_index.md
diff --git a/content/collections/how-to-guides/create-repositories.md b/content/collections/how-to/create-repositories.md
similarity index 98%
rename from content/collections/how-to-guides/create-repositories.md
rename to content/collections/how-to/create-repositories.md
index 4b737cf0..b9b2b3d9 100644
--- a/content/collections/how-to-guides/create-repositories.md
+++ b/content/collections/how-to/create-repositories.md
@@ -1,8 +1,6 @@
 ---
 title: Create repositories
 weight: 1
-aliases:
-  - /collections/how-to/create-repositories/
 ---
 
 # How to create collection repositories
diff --git a/content/collections/how-to-guides/create.md b/content/collections/how-to/create.md
similarity index 82%
rename from content/collections/how-to-guides/create.md
rename to content/collections/how-to/create.md
index 3fff3c1e..2fb1ccd0 100644
--- a/content/collections/how-to-guides/create.md
+++ b/content/collections/how-to/create.md
@@ -1,8 +1,6 @@
 ---
 title: Create a collection
 weight: 3
-aliases:
-  - /collections/how-to/define-metadata/
 ---
 
 # How to create a collection
@@ -11,7 +9,7 @@ You are considering creating a new collection to track terms with Open Terms A
 
 ## Define metadata
 
-First of all, define the [metadata]({{< relref "collections/references/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
+First of all, define the [metadata]({{< relref "collections/reference/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
 
 ## Check existing collections
 
@@ -27,10 +25,10 @@ You can inform the community by posting on the instant messaging system, or [sen
 
 ## Define governance
 
-Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the [governance]({{< relref "collections/references/governance" >}}) of your collection.
+Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the [governance]({{< relref "collections/reference/governance" >}}) of your collection.
 
 At any time, feel free to ask for help or partners in the community.
 
 ## Create repositories
 
-See the [guide to create repositories]({{< relref "collections/how-to-guides/create-repositories" >}}) for your collection.
+See the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}}) for your collection.
diff --git a/content/collections/how-to-guides/define-metadata.md b/content/collections/how-to/define-metadata.md
similarity index 98%
rename from content/collections/how-to-guides/define-metadata.md
rename to content/collections/how-to/define-metadata.md
index 8bb84938..bffe5c67 100644
--- a/content/collections/how-to-guides/define-metadata.md
+++ b/content/collections/how-to/define-metadata.md
@@ -1,8 +1,6 @@
 ---
 title: Define metadata
 weight: 2
-aliases:
-  - /collections/how-to/create/
 ---
 
 # How to define metadata
diff --git a/content/collections/references/_index.md b/content/collections/reference/_index.md
similarity index 100%
rename from content/collections/references/_index.md
rename to content/collections/reference/_index.md
diff --git a/content/collections/references/configuration.md b/content/collections/reference/configuration.md
similarity index 100%
rename from content/collections/references/configuration.md
rename to content/collections/reference/configuration.md
diff --git a/content/collections/references/environment-variables.md b/content/collections/reference/environment-variables.md
similarity index 100%
rename from content/collections/references/environment-variables.md
rename to content/collections/reference/environment-variables.md
diff --git a/content/collections/references/governance.md b/content/collections/reference/governance.md
similarity index 100%
rename from content/collections/references/governance.md
rename to content/collections/reference/governance.md
diff --git a/content/collections/references/metadata.md b/content/collections/reference/metadata.md
similarity index 100%
rename from content/collections/references/metadata.md
rename to content/collections/reference/metadata.md
diff --git a/content/collections/tutorials/_index.md b/content/collections/tutorial/_index.md
similarity index 100%
rename from content/collections/tutorials/_index.md
rename to content/collections/tutorial/_index.md
diff --git a/content/collections/tutorials/create.md b/content/collections/tutorial/create.md
similarity index 96%
rename from content/collections/tutorials/create.md
rename to content/collections/tutorial/create.md
index 00f00884..aacd5ecd 100644
--- a/content/collections/tutorials/create.md
+++ b/content/collections/tutorial/create.md
@@ -1,7 +1,9 @@
 ---
 title: Create your first collection
 weight: 1
-aliases: /collections/create/
+aliases:
+  - /collections/create/
+  - /collections/tutorials/create/
 ---
 
 # Create your first collection
@@ -38,7 +40,7 @@ By the end, you'll have a working collection that tracks changes to a service's
 
 ### Step 2: Create the service declaration
 
-4. Create a file `declarations/Open Terms Archive.json` with the following content. For detailed instructions on how to structure it, follow the [Tracking terms tutorial]({{< relref "/terms/tutorials/track" >}}):
+4. Create a file `declarations/Open Terms Archive.json` with the following content. For detailed instructions on how to structure it, follow the [Tracking terms tutorial]({{< relref "/terms/tutorial/track" >}}):
     ```json
     {
       "name": "Open Terms Archive",
diff --git a/content/community/how-to-guides/_index.md b/content/community/how-to/_index.md
similarity index 100%
rename from content/community/how-to-guides/_index.md
rename to content/community/how-to/_index.md
diff --git a/content/community/how-to-guides/join-community-chat.md b/content/community/how-to/join-community-chat.md
similarity index 98%
rename from content/community/how-to-guides/join-community-chat.md
rename to content/community/how-to/join-community-chat.md
index 5ad18c0d..425d9f8b 100644
--- a/content/community/how-to-guides/join-community-chat.md
+++ b/content/community/how-to/join-community-chat.md
@@ -3,7 +3,6 @@ title: Join the community chat
 aliases:
   - /community/how-to-join-mattermost/
   - /community/how-to/join-mattermost/
-  - /community/how-to/join-community-chat/
 linkTitle: Join the chat
 ---
 
diff --git a/content/deployment/how-to-guides/_index.md b/content/deployment/how-to/_index.md
similarity index 100%
rename from content/deployment/how-to-guides/_index.md
rename to content/deployment/how-to/_index.md
diff --git a/content/deployment/how-to-guides/deploy.md b/content/deployment/how-to/deploy.md
similarity index 99%
rename from content/deployment/how-to-guides/deploy.md
rename to content/deployment/how-to/deploy.md
index 39e9f241..ed9f6356 100644
--- a/content/deployment/how-to-guides/deploy.md
+++ b/content/deployment/how-to/deploy.md
@@ -1,8 +1,6 @@
 ---
 title: Deploy a collection
 weight: 1
-aliases:
-  - /deployment/how-to/deploy/
 ---
 
 # How to deploy a collection
diff --git a/content/deployment/how-to-guides/setup-github-teams.md b/content/deployment/how-to/setup-github-teams.md
similarity index 97%
rename from content/deployment/how-to-guides/setup-github-teams.md
rename to content/deployment/how-to/setup-github-teams.md
index 79c0a93a..f2cf3b8f 100644
--- a/content/deployment/how-to-guides/setup-github-teams.md
+++ b/content/deployment/how-to/setup-github-teams.md
@@ -1,8 +1,6 @@
 ---
 title: Set up GitHub teams
 weight: 2
-aliases:
-  - /deployment/how-to/setup-github-teams/
 ---
 
 # How to set up GitHub teams for a collection
diff --git a/content/federation/how-to-guides/_index.md b/content/federation/how-to/_index.md
similarity index 100%
rename from content/federation/how-to-guides/_index.md
rename to content/federation/how-to/_index.md
diff --git a/content/federation/how-to-guides/join.md b/content/federation/how-to/join.md
similarity index 95%
rename from content/federation/how-to-guides/join.md
rename to content/federation/how-to/join.md
index 3605c00a..7e07c071 100644
--- a/content/federation/how-to-guides/join.md
+++ b/content/federation/how-to/join.md
@@ -1,8 +1,6 @@
 ---
 title: Join the federation
 weight: 3
-aliases:
-  - /federation/how-to/join/
 ---
 
 # How to join the federation
diff --git a/content/federation/references/_index.md b/content/federation/reference/_index.md
similarity index 100%
rename from content/federation/references/_index.md
rename to content/federation/reference/_index.md
diff --git a/content/federation/references/criteria.md b/content/federation/reference/criteria.md
similarity index 95%
rename from content/federation/references/criteria.md
rename to content/federation/reference/criteria.md
index e2e8ae2c..a4c5a831 100644
--- a/content/federation/references/criteria.md
+++ b/content/federation/reference/criteria.md
@@ -7,8 +7,8 @@ weight: 3
 
 A **collection** can **join** the Open Terms Archive **federation** if it abides by the following quality criteria:
 
-1. Clearly defined [collection metadata]({{< relref "collections/references/metadata" >}}).
-2. Clearly defined [collection governance]({{< relref "collections/references/governance" >}}).
+1. Clearly defined [collection metadata]({{< relref "collections/reference/metadata" >}}).
+2. Clearly defined [collection governance]({{< relref "collections/reference/governance" >}}).
 3. The vast majority of **versions** are readable, as evidenced by a sample assessment.
 4. **Frequency** of at least one track a day, as evidenced by snapshots.
 5. Public and open-licensed **declarations**, as evidenced by the `LICENSE` file in the declarations repository.
@@ -18,7 +18,7 @@ A **collection** can **join** the Open Terms Archive **federation** if it abides
 9. Publicly accessible API with median response time under 20ms, as evidenced by uptime tracking logs.
 10. Abide by all Open Terms Archive software and data licenses.
 
-For detailed instructions on joining the federation, refer to the [How to Join the Federation guide]({{< relref "federation/how-to-guides/join" >}}).
+For detailed instructions on joining the federation, refer to the [How to Join the Federation guide]({{< relref "federation/how-to/join" >}}).
 
 ## Disclaimer
 
diff --git a/content/terms/explanations/_index.md b/content/terms/explanation/_index.md
similarity index 100%
rename from content/terms/explanations/_index.md
rename to content/terms/explanation/_index.md
diff --git a/content/terms/explanations/declarations-maintenance.md b/content/terms/explanation/declarations-maintenance.md
similarity index 100%
rename from content/terms/explanations/declarations-maintenance.md
rename to content/terms/explanation/declarations-maintenance.md
diff --git a/content/terms/explanations/range-selectors.md b/content/terms/explanation/range-selectors.md
similarity index 100%
rename from content/terms/explanations/range-selectors.md
rename to content/terms/explanation/range-selectors.md
diff --git a/content/terms/guideline/_index.md b/content/terms/guideline/_index.md
new file mode 100644
index 00000000..82f8dd80
--- /dev/null
+++ b/content/terms/guideline/_index.md
@@ -0,0 +1,4 @@
+---
+title: Guidelines
+weight: 5
+---
diff --git a/content/terms/guidelines/choosing-selectors.md b/content/terms/guideline/choosing-selectors.md
similarity index 92%
rename from content/terms/guidelines/choosing-selectors.md
rename to content/terms/guideline/choosing-selectors.md
index 341bddf9..194e45b9 100644
--- a/content/terms/guidelines/choosing-selectors.md
+++ b/content/terms/guideline/choosing-selectors.md
@@ -1,6 +1,8 @@
 ---
 title: "Choosing selectors"
-aliases: /guidelines/choosing-selectors/
+aliases:
+  - /guidelines/choosing-selectors/
+  - /terms/guidelines/choosing-selectors/
 ---
 
 # Choosing selectors
@@ -9,7 +11,7 @@ Selectors are used in Open Terms Archive declarations to specify the parts of
 
 ## What are selectors
 
-Selectors are used in the [`select`]({{< relref "terms/references#select" >}}) and [`remove`]({{< relref "terms/references#remove" >}}) keys of an Open Terms Archive declaration.
+Selectors are used in the [`select`]({{< relref "terms/reference#select" >}}) and [`remove`]({{< relref "terms/reference#remove" >}}) keys of an Open Terms Archive declaration.
 
 The “selectors” referred to are defined by the [W3C Selectors standard](https://www.w3.org/TR/selectors/), more commonly known as “CSS Selectors”.
 
@@ -164,7 +166,7 @@ If in doubt about a selector, prefer making a wide selection and then removing t
 
 ### Use range selectors
 
-[Range selectors]({{< relref "terms/references#range-selectors" >}}) enable to select content that starts in one block and ends in another block that are not in the same tree. While they are more complex than element selectors, it is preferable to use a range selector whose start and end abide by the guidelines above than to use a bad plain selector.
+[Range selectors]({{< relref "terms/reference#range-selectors" >}}) enable to select content that starts in one block and ends in another block that are not in the same tree. While they are more complex than element selectors, it is preferable to use a range selector whose start and end abide by the guidelines above than to use a bad plain selector.
 
 #### Example
 
diff --git a/content/terms/guidelines/declaring.md b/content/terms/guideline/declaring.md
similarity index 99%
rename from content/terms/guidelines/declaring.md
rename to content/terms/guideline/declaring.md
index 019a5a29..b4330bac 100644
--- a/content/terms/guidelines/declaring.md
+++ b/content/terms/guideline/declaring.md
@@ -1,6 +1,8 @@
 ---
 title: "Declaring terms"
-aliases: /guidelines/declaring/
+aliases:
+  - /guidelines/declaring/
+  - /terms/guideline/declaring/
 ---
 
 # Declaring terms
diff --git a/content/terms/guidelines/reviewing.md b/content/terms/guideline/reviewing.md
similarity index 95%
rename from content/terms/guidelines/reviewing.md
rename to content/terms/guideline/reviewing.md
index 44dc52ef..6a44399f 100644
--- a/content/terms/guidelines/reviewing.md
+++ b/content/terms/guideline/reviewing.md
@@ -1,6 +1,8 @@
 ---
 title: "Reviewing contributions"
-aliases: /guidelines/reviewing/
+aliases:
+  - /guidelines/reviewing/
+  - /terms/guidelines/reviewing/
 ---
 
 # Reviewing contributions
@@ -53,10 +55,10 @@ Your focus should be on two aspects: accuracy and quality.
 
 1. Click on the _Inspect the declaration_ link to view the declaration in a graphical user interface.
 2. Use the link provided in the URL section of the contribution tool to check out the original document.
-3. Verify that the name of the service matches the JSON file and complies with the [guidelines]({{< relref "terms/guidelines/declaring#service-name" >}}).
+3. Verify that the name of the service matches the JSON file and complies with the [guidelines]({{< relref "terms/guideline/declaring#service-name" >}}).
 4. Quickly scan the document to ensure that the correct term type has been selected. To determine the term type, consider who the intended audience is and what the document is discussing. You can also refer to the [terms types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) to find the best term type for the document.
 5. Confirm that the selected area of the document contains only one term type and does not include any other types.
-6. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the [selectors guidelines]({{< relref "terms/guidelines/choosing-selectors" >}}).
+6. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the [selectors guidelines]({{< relref "terms/guideline/choosing-selectors" >}}).
     - Ensure that the significant parts do not include navigation items, contact links, or other insignificant details that may cause confusion by triggering a change detection when the legal terms have actually not been updated.
 7. Verify the version of the document in the contribution tool by clicking on the _Verify version_ button.
 8. Ensure that all checks generated by the OTA-bot are manually checked.
@@ -72,19 +74,19 @@ The pull request created will consist of fewer checks than those that add declar
 
 For pull requests that update declarations, you should focus should be on two things: history file and declaration.
 
-- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/explanations/declarations-maintenance" >}}).
+- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/explanation/declarations-maintenance" >}}).
 - **Declaration:** for `update` pull requests, you only look at the selectors to make sure they are **simple** and also verify the **generated version** is ok.
 
 ### Step-by-step Review Guide
 
 1. Click on the inspect the declaration suggestion link to view contribution using the contribution tool.
-2. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the [selectors guidelines]({{< relref "terms/guidelines/choosing-selectors" >}}).
+2. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the [selectors guidelines]({{< relref "terms/guideline/choosing-selectors" >}}).
 3. Verify the version of the document in the contribution tool by clicking on the `verify version` button.
 4. Open the issue linked with the pull request. Confirm the date when the declaration was last tracked from the bot's comment.
 5. Compare it with the `validUntil` property in the history file under the `Files changes` section of the pull request. If the dates are the same, proceed to approve the pull request.
 6. Merge the contribution.
 
-You can read more about maintaining declarations from the [official documentation]({{< relref "terms/explanations/declarations-maintenance" >}}).
+You can read more about maintaining declarations from the [official documentation]({{< relref "terms/explanation/declarations-maintenance" >}}).
 
 ## When to Make Changes to a Contribution
 
@@ -94,7 +96,7 @@ In some special cases, the correction may have to do with the service name. Such
 
 ### Editing a Service ID
 
-When contributing to the project, reviewers may need to modify the Service ID of a service that is being added for tracking. This is often necessary when the service being tracked is in a language other than English, such as Chinese or French. In these cases, the Service ID usually reflects the transliteration of the service name (written in the native language). The [documentation]({{< relref "terms/references#service-id" >}}) provides more information on this. It is important to note that the contributor can be very crucial in providing an accurate transliteration of the service name especially if the reviewer does not know the service's native language.
+When contributing to the project, reviewers may need to modify the Service ID of a service that is being added for tracking. This is often necessary when the service being tracked is in a language other than English, such as Chinese or French. In these cases, the Service ID usually reflects the transliteration of the service name (written in the native language). The [documentation]({{< relref "terms/reference#service-id" >}}) provides more information on this. It is important to note that the contributor can be very crucial in providing an accurate transliteration of the service name especially if the reviewer does not know the service's native language.
 
 Since the Service ID is used as the file name of the JSON file associated with the service, it is necessary to change the file name to reflect the transliteration. Here are the steps to follow:
 
diff --git a/content/terms/guidelines/targeting.md b/content/terms/guideline/targeting.md
similarity index 87%
rename from content/terms/guidelines/targeting.md
rename to content/terms/guideline/targeting.md
index 3793b1e5..545ee7c6 100644
--- a/content/terms/guidelines/targeting.md
+++ b/content/terms/guideline/targeting.md
@@ -1,6 +1,7 @@
 ---
 title: "Targeting"
-aliases: /guidelines/targeting/
+aliases:
+  - /terms/guidelines/targeting/
 ---
 
 # What to track?
diff --git a/content/terms/guidelines/_index.md b/content/terms/guidelines/_index.md
deleted file mode 100644
index 07956d32..00000000
--- a/content/terms/guidelines/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: "Guidelines"
-weight: 5
----
diff --git a/content/terms/how-to-guides/_index.md b/content/terms/how-to/_index.md
similarity index 100%
rename from content/terms/how-to-guides/_index.md
rename to content/terms/how-to/_index.md
diff --git a/content/terms/how-to-guides/add-terms-using-UI.md b/content/terms/how-to/add-terms-using-UI.md
similarity index 96%
rename from content/terms/how-to-guides/add-terms-using-UI.md
rename to content/terms/how-to/add-terms-using-UI.md
index 29856936..bfafa6e2 100644
--- a/content/terms/how-to-guides/add-terms-using-UI.md
+++ b/content/terms/how-to/add-terms-using-UI.md
@@ -3,7 +3,6 @@ title: Add terms with the graphical contribution interface
 linkTitle: Add terms with UI
 aliases: 
   - /terms/how-to-add-terms-using-with-the-graphical-contribution-interface/
-  - /terms/how-to/add-terms-using-ui/
 ---
 
 # How to add terms with the graphical contribution interface
diff --git a/content/terms/how-to-guides/be-notified.md b/content/terms/how-to/be-notified.md
similarity index 92%
rename from content/terms/how-to-guides/be-notified.md
rename to content/terms/how-to/be-notified.md
index d2450eca..b9b9dd5f 100644
--- a/content/terms/how-to-guides/be-notified.md
+++ b/content/terms/how-to/be-notified.md
@@ -3,7 +3,6 @@ title: Be notified of terms changes
 aliases:
   - /subscribe-rss/
   - /terms/how-to-be-notified-of-terms-changes/
-  - /terms/how-to/be-notified/
 ---
 
 # How to be notified of terms changes
@@ -16,7 +15,7 @@ An RSS feed is a type of web page that contains information about the latest con
 
 To find out the address of the RSS feed you want to subscribe to:
 
-1. [Navigate]({{< relref "/analysis/how-to-guides/navigate-history" >}}) to the page with the history of changes you are interested in.
+1. [Navigate]({{< relref "/analysis/how-to/navigate-history" >}}) to the page with the history of changes you are interested in.
     - For example, for the GitHub Privacy Policy of the Demo collection, this would be [this page](https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md).
 2. Copy the address of that page from your browser’s address bar.
     - For example, for the GitHub Privacy Policy of the Demo collection, this would be `https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md`.
diff --git a/content/terms/how-to-guides/declarations-maintenance-inspector-open-get-datetime.png b/content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png
similarity index 100%
rename from content/terms/how-to-guides/declarations-maintenance-inspector-open-get-datetime.png
rename to content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png
diff --git a/content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-last-month.png b/content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png
similarity index 100%
rename from content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-last-month.png
rename to content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png
diff --git a/content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-reopened-issue.png b/content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png
similarity index 100%
rename from content/terms/how-to-guides/declarations-maintenance-ota-bot-comment-reopened-issue.png
rename to content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png
diff --git a/content/terms/how-to-guides/declarations-maintenance-ota-bot-comment.png b/content/terms/how-to/declarations-maintenance-ota-bot-comment.png
similarity index 100%
rename from content/terms/how-to-guides/declarations-maintenance-ota-bot-comment.png
rename to content/terms/how-to/declarations-maintenance-ota-bot-comment.png
diff --git a/content/terms/how-to-guides/get-the-validUntil-date-from-an-issue.md b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md
similarity index 93%
rename from content/terms/how-to-guides/get-the-validUntil-date-from-an-issue.md
rename to content/terms/how-to/get-the-validUntil-date-from-an-issue.md
index 6c8ceb6c..ec255e55 100644
--- a/content/terms/how-to-guides/get-the-validUntil-date-from-an-issue.md
+++ b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md
@@ -1,8 +1,6 @@
 ---
 title: How to guides get the `validUntil`
 linkTitle: Get the `validUntil` date
-aliases:
-  - /terms/how-to/get-the-validuntil-date-from-an-issue/
 ---
 
 # How to get the `validUntil` date
diff --git a/content/terms/how-to-guides/rename-a-service.md b/content/terms/how-to/rename-a-service.md
similarity index 50%
rename from content/terms/how-to-guides/rename-a-service.md
rename to content/terms/how-to/rename-a-service.md
index 33e89281..ff24155f 100644
--- a/content/terms/how-to-guides/rename-a-service.md
+++ b/content/terms/how-to/rename-a-service.md
@@ -1,10 +1,8 @@
 ---
 title: How to guides rename a service
 linkTitle: Rename a service
-aliases:
-  - /terms/how-to/rename-a-service/
 ---
 
 # How to rename a service
 
-The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to-guides/track-new-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms.
+The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to/track-new-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms.
diff --git a/content/terms/how-to-guides/terminate-a-service.md b/content/terms/how-to/terminate-a-service.md
similarity index 93%
rename from content/terms/how-to-guides/terminate-a-service.md
rename to content/terms/how-to/terminate-a-service.md
index 6978a6be..c0ce5ffb 100644
--- a/content/terms/how-to-guides/terminate-a-service.md
+++ b/content/terms/how-to/terminate-a-service.md
@@ -1,8 +1,6 @@
 ---
 title: How to guides terminate a service
 linkTitle: Terminate a service
-aliases:
-  - /terms/how-to/terminate-a-service/
 ---
 
 # How to terminate a service
diff --git a/content/terms/how-to-guides/test-declaration.md b/content/terms/how-to/test-declaration.md
similarity index 100%
rename from content/terms/how-to-guides/test-declaration.md
rename to content/terms/how-to/test-declaration.md
diff --git a/content/terms/how-to-guides/track-new-terms.md b/content/terms/how-to/track-new-terms.md
similarity index 91%
rename from content/terms/how-to-guides/track-new-terms.md
rename to content/terms/how-to/track-new-terms.md
index fce8928f..a936fec2 100644
--- a/content/terms/how-to-guides/track-new-terms.md
+++ b/content/terms/how-to/track-new-terms.md
@@ -3,7 +3,6 @@ title: Track new terms
 weight: 2
 aliases: 
   - /contributing-terms/
-  - /terms/how-to/track-new-terms/
 ---
 
 # How to track new terms
@@ -31,7 +30,7 @@ To add a declaration, you need to follow these steps:
 6. After you've properly added your selectors and structured your JSON file, you need to test and validate your JSON file to make sure it is ok. To do this, you need to run `npx ota validate --services [service name]` from the root of the repository. This will run a validation on the declaration, highlighting any changes required.
 7. If all tests are good, make a pull request to the main repository.  
 
-> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guidelines/declaring" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂
+> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guideline/declaring" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂
 
 ## Service name
 
@@ -53,7 +52,7 @@ The service name is exposed to end users. It should reflect as closely as possib
   - _Example: `Firebase` (by Google) → `Firebase`_.
   - _Example: `App Store` (by Apple) → `App Store`_.
 
-> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guidelines/declaring#service-name" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂
+> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guideline/declaring#service-name" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂
 
 ## Service ID
 
@@ -73,7 +72,7 @@ The service ID is exposed to developers. It should be easy to handle with script
   - _Example: `App Store` → `App Store`_.
   - _Example: `DeviantArt` → `DeviantArt`_.
 
-> If you have a hard time defining the service ID, check out the [practical guidelines to derive the ID from the service name]({{< relref "/terms/guidelines/declaring#service-id" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂
+> If you have a hard time defining the service ID, check out the [practical guidelines to derive the ID from the service name]({{< relref "/terms/guideline/declaring#service-id" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂
 
 > More details on the ID and naming constraints and recommendations can be found in the relevant [decision record](https://github.com/OpenTermsArchive/engine/blob/main/decision-records/0001-service-name-and-id.md).
 
diff --git a/content/terms/references/_index.md b/content/terms/reference/_index.md
similarity index 100%
rename from content/terms/references/_index.md
rename to content/terms/reference/_index.md
diff --git a/content/terms/references/declaration.md b/content/terms/reference/declaration.md
similarity index 98%
rename from content/terms/references/declaration.md
rename to content/terms/reference/declaration.md
index 36962cc7..b9c1f154 100644
--- a/content/terms/references/declaration.md
+++ b/content/terms/reference/declaration.md
@@ -1,6 +1,6 @@
 ---
 title: "Service declaration"
-aliases: "/terms/references/"
+aliases: "/terms/reference/"
 ---
 
 # Service declaration
@@ -140,7 +140,7 @@ As an array of those:
 {{< refItem
     name="filter"
     type="array of strings"
-    description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"terms/references/filters\" >}}) section for more information."
+    description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"terms/reference/filters\" >}}) section for more information."
     example="[\"filterName1\", \"filterName2\"]"
 />}}
 
diff --git a/content/terms/references/filters.md b/content/terms/reference/filters.md
similarity index 97%
rename from content/terms/references/filters.md
rename to content/terms/reference/filters.md
index 3a638065..6006c8a0 100644
--- a/content/terms/references/filters.md
+++ b/content/terms/reference/filters.md
@@ -25,7 +25,7 @@ Each filter is exposed as a named function export that takes a `document` parame
 
 > The `document` parameter is actually a [JSDOM](https://github.com/jsdom/jsdom) document instance.
 
-You can learn more about usual noise and ways to handle it [in the guidelines]({{< relref "/terms/guidelines/declaring#usual-noise" >}}).
+You can learn more about usual noise and ways to handle it [in the guidelines]({{< relref "/terms/guideline/declaring#usual-noise" >}}).
 
 ### Example
 
diff --git a/content/terms/tutorials/_index.md b/content/terms/tutorial/_index.md
similarity index 100%
rename from content/terms/tutorials/_index.md
rename to content/terms/tutorial/_index.md
diff --git a/content/terms/tutorials/track.md b/content/terms/tutorial/track.md
similarity index 98%
rename from content/terms/tutorials/track.md
rename to content/terms/tutorial/track.md
index 36d171cb..c964f595 100644
--- a/content/terms/tutorials/track.md
+++ b/content/terms/tutorial/track.md
@@ -1,5 +1,7 @@
 ---
 title: Track your first terms
+aliases:
+  - /terms/tutorial/track/
 ---
 
 # Track your first terms

From 18ac45183b2ae3fcee2cec12640d50b9589ab4d6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Wed, 2 Apr 2025 17:38:10 +0200
Subject: [PATCH 18/20] Add missing aliases

---
 content/terms/guideline/declaring.md | 2 +-
 content/terms/tutorial/track.md      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/content/terms/guideline/declaring.md b/content/terms/guideline/declaring.md
index b4330bac..a1cb0ee7 100644
--- a/content/terms/guideline/declaring.md
+++ b/content/terms/guideline/declaring.md
@@ -2,7 +2,7 @@
 title: "Declaring terms"
 aliases:
   - /guidelines/declaring/
-  - /terms/guideline/declaring/
+  - /terms/guidelines/declaring/
 ---
 
 # Declaring terms
diff --git a/content/terms/tutorial/track.md b/content/terms/tutorial/track.md
index c964f595..6ac25006 100644
--- a/content/terms/tutorial/track.md
+++ b/content/terms/tutorial/track.md
@@ -1,7 +1,7 @@
 ---
 title: Track your first terms
 aliases:
-  - /terms/tutorial/track/
+  - /terms/tutorials/track/
 ---
 
 # Track your first terms

From 6c9143f7a71261e586d33b3e6b2485315634b878 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Cl=C3=A9ment=20Biron?= <clement.biron@gmail.com>
Date: Thu, 3 Apr 2025 10:11:46 +0200
Subject: [PATCH 19/20] Removes duplicates

---
 content/terms/how-to/get-the-validUntil-date-from-an-issue.md | 2 +-
 content/terms/how-to/rename-a-service.md                      | 2 +-
 content/terms/how-to/terminate-a-service.md                   | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md
index ec255e55..4478d4b2 100644
--- a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md
+++ b/content/terms/how-to/get-the-validUntil-date-from-an-issue.md
@@ -1,5 +1,5 @@
 ---
-title: How to guides get the `validUntil`
+title: How to get the `validUntil`
 linkTitle: Get the `validUntil` date
 ---
 
diff --git a/content/terms/how-to/rename-a-service.md b/content/terms/how-to/rename-a-service.md
index ff24155f..59871a5c 100644
--- a/content/terms/how-to/rename-a-service.md
+++ b/content/terms/how-to/rename-a-service.md
@@ -1,5 +1,5 @@
 ---
-title: How to guides rename a service
+title: How to rename a service
 linkTitle: Rename a service
 ---
 
diff --git a/content/terms/how-to/terminate-a-service.md b/content/terms/how-to/terminate-a-service.md
index c0ce5ffb..7c3a923b 100644
--- a/content/terms/how-to/terminate-a-service.md
+++ b/content/terms/how-to/terminate-a-service.md
@@ -1,5 +1,5 @@
 ---
-title: How to guides terminate a service
+title: How to terminate a service
 linkTitle: Terminate a service
 ---
 

From 7e5455ed719a769cdc0c455ec9a2dce1ad73b727 Mon Sep 17 00:00:00 2001
From: Matti Schneider <matti@opentermsarchive.org>
Date: Thu, 3 Apr 2025 11:06:00 +0200
Subject: [PATCH 20/20] Correct sub-sections order

Follow Diataxis
---
 content/terms/explanation/_index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/terms/explanation/_index.md b/content/terms/explanation/_index.md
index b18c0ef5..381720df 100644
--- a/content/terms/explanation/_index.md
+++ b/content/terms/explanation/_index.md
@@ -1,4 +1,4 @@
 ---
 title: Explanations
-weight: 2
+weight: 4
 ---