OpenTermsArchive · MattiSG · Apr 3, 2025 · Mar 27, 2025 · Mar 27, 2025 · Mar 31, 2025
diff --git 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

diff --git a/content/analysis/how-to-guides/_index.md b/content/analysis/how-to-guides/_index.md
@@ -0,0 +1,4 @@
+---
+title: How to guides
+weight: 1
+---
diff --git a/content/analysis/how-to/navigate-history.md → ...nalysis/how-to-guides/navigate-history.md b/content/analysis/how-to/navigate-history.md → ...nalysis/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 → ...nt/analysis/how-to-guides/publish-memo.md b/content/analysis/how-to/publish-memo.md → ...nt/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/analysis/how-to/_index.md b/content/analysis/how-to/_index.md
diff --git 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
@@ -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/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:
 
-{{< 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/how-to-guides/_index.md b/content/collections/how-to-guides/_index.md
@@ -0,0 +1,5 @@
+---
+title: How to guides
+weight: 2
+---
+
diff --git a/...collections/how-to/create-repositories.md → ...ions/how-to-guides/create-repositories.md b/...collections/how-to/create-repositories.md → ...ions/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/create.md → content/collections/how-to-guides/create.md b/content/collections/how-to/create.md → 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
@@ -9,7 +11,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 +27,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/...ent/collections/how-to/define-metadata.md → ...lections/how-to-guides/define-metadata.md b/...ent/collections/how-to/define-metadata.md → ...lections/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/collections/how-to/_index.md b/content/collections/how-to/_index.md
diff --git a/content/collections/reference/environment-variables.md b/content/collections/reference/environment-variables.md
diff --git a/content/terms/reference/_index.md → content/collections/references/_index.md b/content/terms/reference/_index.md → content/collections/references/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Reference
+title: References
 weight: 3
 ---