wip

Ndpnt · Ndpnt · commit afa97854e7ad · 2025-05-28T14:43:53.000+02:00
diff --git a/content/_index.md b/content/_index.md
@@ -3,39 +3,29 @@ title: Introduction
 weight: 1
 ---
 
-# Introduction
+# Welcome to the Open Terms Archive documentation
 
+Open Terms Archive is a decentralised system that tracks collections of services' terms across multiple servers. Each collection exposes the data it collects through datasets and through its own API. The Federation API unifies search and discovery across collections.
 
-# Open Terms Archive documentation
 
-Open Terms Archive is a decentralised system that tracks collections of services' terms across multiple servers. Each collection exposes the data it collects through datasets and through its own API. The Federation API unifies search and discovery across collections.
+## Documentation structure
 
-## Required minimal terminology
+This documentation follows the [Diátaxis](https://diataxis.fr) approach and is structured in following categories
 
-Before diving into the details, let's first understand the essential terminology used throughout this documentation.
+### Tutorials
 
-- **Terms:** the contractual documents published by services (such as Terms of Service, Privacy Policy, Community Guidelines…) that users agree to.
-- **Collection:** a set of tracked terms grouped by a specific scope (such as language, jurisdiction, industry…).
-- **Declaration:** a JSON file that defines which terms to track for a service and how to track them.
-- **Snapshot:** the original source document (HTML, PDF…) from which the terms will be extracted.
-- **Version:** the textual content of the terms after filtering out irrelevant content (navigation menu, advertisements…) from a snapshot.
+step-by-step learning guides that help beginners get started with Open Terms Archive, providing foundational knowledge and hands-on experience.
 
-## Documentation structure
+### How-to guides
+
+Task-focused instructions that help experienced users accomplish specific goals efficiently and effectively.
+
+### References
+
+Comprehensive technical documentation detailing configuration options and specifications for advanced users.
 
-This documentation follows the [Diátaxis](https://diataxis.fr) approach and structures content in different categories:
+### Explanations
 
-- **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.
-- **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.
+Background knowledge that enables understanding the constraints and how choices that are made.
 
-### Table of contents
 
-- **Analysis:** guidance on how to analyze terms changes, from navigating through the history of tracked terms to publishing memos about significant changes.
-- **Community:** information on how to participate in the Open Terms Archive community.
-- **Terms:** guidance on tracking and maintaining terms declarations.
-- **Collections:** guidance on creating and managing collections of tracked terms.
-- **Federation:** constraints and benefits of joining the Open Terms Archive federation.
-- **Deployment:** guidance on operating an Open Terms Archive instance.
-- **Programmatic access:** documentation on the engine CLI and APIs.
-- **Concepts and principles:** main concepts, terminology and fundamental design principles of Open Terms Archive.
diff --git a/content/explanations/community/federation-benefits.md b/content/explanations/community/federation-benefits.md
@@ -1,5 +1,5 @@
 ---
-title: Federation Benefits
+title: Federation benefits
 weight: 1
 ---
 
diff --git a/content/explanations/terms-tracking/service-name-noise copy.md b/content/explanations/terms-tracking/service-name-noise copy.md
@@ -0,0 +1,6 @@
+---
+title: Tracking noise
+weight: 5
+---
+
+# Service name usual noise
diff --git a/content/explanations/terms-tracking/service-name-noise.md b/content/explanations/terms-tracking/service-name-noise.md
@@ -1,5 +1,5 @@
 ---
-title: Service name usual noise
+title: Service naming
 weight: 5
 ---
 
diff --git a/content/explanations/terms-tracking/terms-types.md b/content/explanations/terms-tracking/terms-types.md
@@ -1,5 +1,5 @@
 ---
-title: Terms types
+title: Terms categories
 weight: 3
 ---
 
diff --git a/content/how-to/analysis/_index.md b/content/how-to/analysis/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Analysis
+title: Terms analysis
 weight: 1
 ---
diff --git a/content/how-to/analysis/navigate-history.md b/content/how-to/analysis/navigate-history.md
@@ -1,5 +1,5 @@
 ---
-title: Navigate history
+title: Browse terms history
 weight: 3
 ---
 
diff --git a/content/how-to/analysis/notify-changes.md b/content/how-to/analysis/notify-changes.md
@@ -1,5 +1,5 @@
 ---
-title: Be notified on changes
+title: Monitor terms changes
 weight: 2
 ---
 
diff --git a/content/how-to/analysis/publish-memo.md b/content/how-to/analysis/publish-memo.md
@@ -1,5 +1,5 @@
 ---
-title: Publish a memo
+title: Publish memos
 weight: 4
 ---
 
diff --git a/content/how-to/collection-lifecycle/review-contributions.md b/content/how-to/collection-lifecycle/review-contributions.md
@@ -1,5 +1,5 @@
 ---
-title: Reviewing contributions
+title: Review contributions
 weight: 7
 ---
 
diff --git a/content/how-to/deployment/overview.md b/content/how-to/deployment/overview.md
@@ -1,5 +1,5 @@
 ---
-title: Overview
+title: Deploy a collection
 weight: 2
 ---
 
diff --git a/content/how-to/tracking/_index.md b/content/how-to/tracking/_index.md
@@ -1,4 +1,4 @@
 ---
-title: Tracking
+title: Terms tracking
 weight: 2
 ---
diff --git a/content/how-to/tracking/get-valid-until.md b/content/how-to/tracking/get-valid-until.md
@@ -1,5 +1,5 @@
 ---
-title: Get the validUntil date
+title: Define validity periods
 weight: 5
 ---
 
diff --git a/content/how-to/tracking/manage-custom-terms.md b/content/how-to/tracking/manage-custom-terms.md
@@ -1,5 +1,5 @@
 ---
-title: Manage a custom terms type
+title: Manage custom terms types
 weight: 6
 ---
 
diff --git a/content/how-to/tracking/rename-service.md b/content/how-to/tracking/rename-service.md
@@ -1,5 +1,5 @@
 ---
-title: Rename a service
+title: Update service names
 weight: 7
 ---
 
diff --git a/content/how-to/tracking/terminate-service.md b/content/how-to/tracking/terminate-service.md
@@ -1,5 +1,5 @@
 ---
-title: Terminate a service
+title: End service tracking
 weight: 8
 ---
 
diff --git a/content/how-to/tracking/test-declarations.md b/content/how-to/tracking/test-declarations.md
@@ -1,5 +1,5 @@
 ---
-title: Test declarations
+title: Validate declarations
 weight: 4
 ---
 
diff --git a/content/how-to/tracking/track-new-terms.md b/content/how-to/tracking/track-new-terms.md
@@ -1,5 +1,5 @@
 ---
-title: Track new terms
+title: Track new services
 weight: 2
 ---
 
diff --git a/content/how-to/tracking/track-with-ui.md b/content/how-to/tracking/track-with-ui.md
@@ -1,5 +1,5 @@
 ---
-title: Track new terms with UI
+title: Track services with UI
 weight: 3
 ---
 
diff --git a/content/reference/analysis/_index.md b/content/reference/analysis/_index.md
@@ -0,0 +1,4 @@
+---
+title: Terms analysis
+weight: 1
+---
diff --git a/content/reference/analysis/memo-copywriting.md b/content/reference/analysis/memo-copywriting.md
diff --git a/content/reference/community/federation-criteria.md b/content/reference/community/federation-criteria.md
@@ -1,5 +1,5 @@
 ---
-title: Federation Criteria
+title: Federation criteria
 weight: 2
 ---
 
diff --git a/content/reference/deployment/architecture.md b/content/reference/deployment/architecture.md
@@ -1,5 +1,5 @@
 ---
-title: Architecture
+title: System architecture
 weight: 1
 ---
 
diff --git a/content/reference/programmatic-access/node-module.md b/content/reference/programmatic-access/node-module.md
@@ -11,53 +11,41 @@ As a Node module dependency, the engine exposes a JavaScript API that can be cal
 
 #### Classes
 
-* [Record](#Record)
-    * [`new Record()`](#new_Record_new)
-
-#### Constants
-
-* [`router`](#router)
+* [SourceDocument](#SourceDocument)
+    * [`new SourceDocument(params)`](#new_SourceDocument_new)
 
 #### Functions
 
 * [`extract(sourceDocument)`](#extract) ⇒ <code>Promise.&lt;string&gt;</code>
-* [`fetch(params)`](#fetch) ⇒ <code>Promise</code>
-* ~~[`normalizeConfig()`](#normalizeConfig)~~
+* [`launchHeadlessBrowser()`](#launchHeadlessBrowser) ⇒ <code>Promise.&lt;puppeteer.Browser&gt;</code>
+* [`stopHeadlessBrowser()`](#stopHeadlessBrowser) ⇒ <code>Promise.&lt;void&gt;</code>
+* [`fetch(params)`](#fetch) ⇒ <code>Promise.&lt;{mimeType: string, content: (string\|Buffer)}&gt;</code>
 
 ---
 
-<a name="Record"></a>
+<a name="SourceDocument"></a>
 
-#### Record
+#### SourceDocument
 **Kind**: global class  
-<a name="new_Record_new"></a>
-
-##### `new Record()`
-Abstract Class Record.
-
-<a name="router"></a>
-
-#### `router`
-**Kind**: global constant  
-**Swagger**: tags:
-  name: Versions
-  description: Versions API
-components:
-  schemas:
-    Version:
-      type: object
-      description: Version content and metadata
-      properties:
-        fetchDate:
-          type: string
-          format: date-time
-          description: The ISO 8601 datetime string when the version was recorded.
-        id:
-          type: string
-          description: The ID of the version.
-        content:
-          type: string
-          description: The JSON-escaped Markdown content of the version.  
+<a name="new_SourceDocument_new"></a>
+
+##### `new SourceDocument(params)`
+Represents a source document containing web content and metadata for extraction.
+Includes the document location, selectors for content inclusion/exclusion,
+content filters, raw content data, and MIME type information.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| params | <code>object</code> | The source document parameters |
+| params.location | <code>string</code> | The URL location of the document |
+| params.executeClientScripts | <code>boolean</code> | Whether to execute client-side scripts |
+| params.contentSelectors | <code>string</code> \| <code>object</code> \| <code>Array</code> | CSS selectors for content to include |
+| params.insignificantContentSelectors | <code>string</code> \| <code>object</code> \| <code>Array</code> | CSS selectors for content to exclude |
+| params.filters | <code>Array</code> | Array of filters to apply |
+| params.content | <code>string</code> | The document content |
+| params.mimeType | <code>string</code> | The MIME type of the content |
+
 <a name="extract"></a>
 
 #### `extract(sourceDocument)` ⇒ <code>Promise.&lt;string&gt;</code>
@@ -68,44 +56,38 @@ Extract content from source document and convert it to Markdown
 
 | Param | Type | Description |
 | --- | --- | --- |
-| sourceDocument | <code>string</code> | Source document from which to extract content, see [./src/archivist/services/sourceDocument.js](./src/archivist/services/sourceDocument.js) |
+| sourceDocument | <code>string</code> | Source document from which to extract content, see [SourceDocument](#SourceDocument) |
+
+<a name="launchHeadlessBrowser"></a>
+
+#### `launchHeadlessBrowser()` ⇒ <code>Promise.&lt;puppeteer.Browser&gt;</code>
+Launches a headless browser instance using Puppeteer if one is not already running. Returns the existing browser instance if one is already running, otherwise creates and returns a new instance.
 
+**Kind**: global function  
+**Returns**: <code>Promise.&lt;puppeteer.Browser&gt;</code> - The Puppeteer browser instance.  
+<a name="stopHeadlessBrowser"></a>
+
+#### `stopHeadlessBrowser()` ⇒ <code>Promise.&lt;void&gt;</code>
+Stops the headless browser instance if one is running. If no instance exists, it does nothing.
+
+**Kind**: global function  
 <a name="fetch"></a>
 
-#### `fetch(params)` ⇒ <code>Promise</code>
+#### `fetch(params)` ⇒ <code>Promise.&lt;{mimeType: string, content: (string\|Buffer)}&gt;</code>
 Fetch a resource from the network, returning a promise which is fulfilled once the response is available
 
 **Kind**: global function  
-**Returns**: <code>Promise</code> - @returns {Promise<Object>} Promise which will be resolved with an object containing the `mimeType` and the `content` of the URL as string or Buffer  
+**Returns**: <code>Promise.&lt;{mimeType: string, content: (string\|Buffer)}&gt;</code> - Promise containing the fetched resource's MIME type and content  
 
 | Param | Type | Description |
 | --- | --- | --- |
-| params | <code>Object</code> | Fetcher parameters |
+| params | <code>object</code> | Fetcher parameters |
 | params.url | <code>string</code> | URL of the resource you want to fetch |
 | [params.executeClientScripts] | <code>boolean</code> | Enable execution of client scripts. When set to `true`, this property loads the page in a headless browser to load all assets and execute client scripts before returning its content |
 | [params.cssSelectors] | <code>string</code> \| <code>Array</code> | List of CSS selectors to await when loading the resource in a headless browser. Can be a CSS selector or an array of CSS selectors. Only relevant when `executeClientScripts` is enabled |
-| [params.config] | <code>Object</code> | Fetcher configuration |
+| [params.config] | <code>object</code> | Fetcher configuration |
 | [params.config.navigationTimeout] | <code>number</code> | Maximum time (in milliseconds) to wait before considering the fetch failed |
 | [params.config.language] | <code>string</code> | Language (in [ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)) to be passed in request headers |
 | [params.config.waitForElementsTimeout] | <code>number</code> | Maximum time (in milliseconds) to wait for selectors to exist on page before considering the fetch failed. Only relevant when `executeClientScripts` is enabled |
 
-<a name="normalizeConfig"></a>
-
-#### ~~`normalizeConfig()`~~
-***Deprecated***
-
-Support for legacy config format where reporter configuration was nested under `githubIssues`
-Example:
-
-```json
-{
-  "githubIssues": {
-    "repositories": {
-      "declarations": "OpenTermsArchive/sandbox-declarations"
-    }
-  }
-}
-```
-
-**Kind**: global function  
 <!-- markdownlint-enable -->
diff --git a/content/reference/terms/service-declaration.md b/content/reference/terms/service-declaration.md
@@ -1,5 +1,5 @@
 ---
-title: Service declaration
+title: Service declarations
 weight: 3
 ---
 
diff --git a/content/reference/terms/service-naming.md b/content/reference/terms/service-naming.md
@@ -1,5 +1,5 @@
 ---
-title: Service naming
+title: Service naming conventions
 weight: 5
 ---
 
diff --git a/content/tutorials/create-collection copy.md b/content/tutorials/create-collection copy.md
@@ -0,0 +1,6 @@
+---
+title: Track your first terms
+weight: 1
+---
+
+# Create your first collection
diff --git a/themes/opentermsarchive/assets/css/components/aside.css b/themes/opentermsarchive/assets/css/components/aside.css
diff --git a/themes/opentermsarchive/layouts/partials/aside.html b/themes/opentermsarchive/layouts/partials/aside.html
