Update metadata documentation

content/collections/create.en.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/metadata" >}}) of the collection you would like to create.
+First of all, define the [metadata]({{< relref "collections/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories.
 
 ## Check existing collections
 
@@ -80,6 +80,10 @@ Issues labels will be added by the engine as problems are encountered when track
 
 - Update the README file with proper metadata: topic, maintainers, jurisdictions, languages…
 
+#### Update metadata
+
+- Update the metadata file `metadata.yml` with the collection metadata you defined earlier.
+
 ### Snapshots
 
 Create the snapshots repository by using the [`demo-snapshots` repository](https://github.com/OpenTermsArchive/demo-snapshots) as template:

content/collections/metadata.en.md

@@ -7,61 +7,149 @@ weight: 1
 
 A collection is defined by the following metadata.
 
-## Description
-
-A concise description of the collection topic.
-
-### Examples
-
-- Largest global social media
-- Most used social media in France
-- Dating apps
-- Platforms providing services to businesses
-
-## Name
-
-Three words maximum.
-
-### Examples
-
-- Platform Governance Archive
-- France Élections
-- Dating
-- P2B Compliance Assessment
-
-## ID
-
-An identifier derived from the collection name that can more easily be referenced in code. Use acronyms and replace spaces with dashes.
-
-### Examples
-
-- `pga`
-- `France-elections`
-- `dating`
-- `p2b-compliance`
-
-## Language
-
-The expected language of the terms in the collection.
-
-### Examples
-
-- `English`
-- `French`
-- `All EU languages`
-
-## Jurisdiction
-
-The expected jurisdiction in which the terms in the collection apply.
-
-### Examples
-
-- `EU`
-- `France`
-- `EEA`
-- `USA`
-- `global`
-
-## Roles
-
-The name, URL and logo of the entities that will take responsibility for each of the necessary governance [roles]({{< relref "collections/governance" >}}).
+## Required fields
+
+| Field | Type | Description |
+|----------------|-----------------|---------------------------------------|
+| `name` | string | Display name of the collection (max 3 words) |
+| `id` | string | Unique identifier derived from name (acronyms, dash-separated) |
+| `tagline` | string | Concise description of collection topic |
+| `description` | string | Detailed context beyond tagline |
+| `languages` | Array of strings| [ISO 639 language codes](https://en.wikipedia.org/wiki/ISO_639) allowed in collection |
+| `jurisdictions`| Array of strings| [ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) for covered jurisdictions |
+
+Example:
+
+```yaml
+name: Platform Governance Archive
+id: pga
+tagline: Largest global social media
+languages: [en, fr, de]
+jurisdictions: [EU]
+```
+
+## Additional fields
+
+Additional fields are optional but highly recommended to facilitate better discovery, comprehension, and utilization of the collection.
+
+| Field | Type | Description |
+|----------------|-----------------|---------------------------------------|
+| `description` | string | Detailed context beyond tagline |
+| `dataset` | url | URL to released versions dataset |
+| `declarations` | url | URL to declarations repository |
+| `versions` | url | URL to versions repository |
+| `snapshots` | url | URL to snapshots repository |
+| `logo` | url | URL to the collection's logo. Optimized PNG transparent image (min width 240px) |
+| `donation` | url | URL to donation page |
+| `trackingPeriods`| tracking periods object | see [Tracking periods](#tracking-periods) section |
+| `governance` | governance object | see [Governance](#governance) section |
+
+Example:
+
+```yaml
+description: Comprehensive collection of terms of service from major global social media platforms.
+dataset: https://github.com/OpenTermsArchive/demo-versions/releases
+declarations: https://github.com/OpenTermsArchive/demo-declarations
+versions: https://github.com/OpenTermsArchive/demo-versions
+snapshots: https://github.com/OpenTermsArchive/demo-snapshots
+logo: https://opentermsarchive.org/images/collections/demo.png
+donation: https://opencollective.com/opentermsarchive
+```
+
+### Tracking periods
+
+Information about when and how terms are tracked:
+
+| Field | Type | Description |
+|---------------|--------|--------------------------------------------|
+| `startDate` | date ([ISO 8601 format: YYYY-MM-DD](https://en.wikipedia.org/wiki/ISO_8601)) | The date when tracking started |
+| `endDate` | date ([ISO 8601 format: YYYY-MM-DD](https://en.wikipedia.org/wiki/ISO_8601)) | The date when tracking ended or will end. If not specified, tracking is ongoing. |
+| `schedule` | string | A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency |
+| `serverLocation`| string (city name, [ISO 3166-2 country code](https://en.wikipedia.org/wiki/ISO_3166-2)) | The geographic location of the tracking server |
+
+Example:
+
+```yaml
+trackingPeriods:
+  startDate: 2023-01-01
+  endDate: 2024-12-31
+  schedule: "0 0 * * *"
+  serverLocation: London, GB
+```
+
+### Governance
+
+Organizations responsible for collection roles:
+
+| Field | Type | Description |
+|---------------|-----------------|----------------------------------------|
+| `hosts` | Array of organizations objects| Organizations hosting the collection |
+| `administrators`| Array of organizations objects| Organizations managing the collection |
+| `curators` | Array of organizations objects| Organizations curating the content |
+| `maintainers` | Array of organizations objects| Organizations maintaining the technical aspects |
+| `sponsors` | Array of organizations objects| Organizations providing support |
+
+Each organization in the governance roles is defined by the following fields:
+
+| Field | Type | Description |
+|---------------|--------|-------------------------------------------|
+| `name` | string | Name of the organization |
+| `url` | url | Website URL of the organization (optional) |
+| `logo` | url | URL to the organization's logo. Optimized PNG transparent image (min width 240px) (optional) |
+
+Example:
+
+```yaml
+governance:
+  administrators:
+    - name: Open Terms Archive
+      url: https://opentermsarchive.org/
+      logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
+  curators: []
+  maintainers: []
+  hosts: []
+  sponsors: []
+```
+
+## Complete metadata example
+
+```yaml
+id: demo
+name: Demo
+tagline: Services needed to operate the Open Terms Archive engine
+description: This demo collection serves as a reference implementation…
+dataset: https://github.com/OpenTermsArchive/demo-versions/releases
+declarations: https://github.com/OpenTermsArchive/demo-declarations
+versions: https://github.com/OpenTermsArchive/demo-versions
+snapshots: https://github.com/OpenTermsArchive/demo-snapshots
+logo: https://opentermsarchive.org/images/collections/demo.png
+donation: https://opencollective.com/opentermsarchive
+languages: [en]
+jurisdictions: [EU]
+trackingPeriods:
+  startDate: 2023-01-01
+  endDate: 2024-12-31
+  schedule: "0 0 * * *"
+  serverLocation: London, GB
+governance:
+  hosts: 
+    - name: Ministry for Europe and Foreign Affairs
+      url: https://www.diplomatie.gouv.fr/en/
+      logo: https://opentermsarchive.org/images/contributors/meae.png
+  administrators:
+    - name: Open Terms Archive
+      url: https://opentermsarchive.org/
+      logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
+  curators:
+    - name: Open Terms Archive
+      url: https://opentermsarchive.org/
+      logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
+  maintainers:
+    - name: Open Terms Archive
+      url: https://opentermsarchive.org/
+      logo: https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png
+  sponsors: 
+    - name: Ministry for Europe and Foreign Affairs
+      url: https://www.diplomatie.gouv.fr/en/
+      logo: https://opentermsarchive.org/images/contributors/meae.png
+```

themes/opentermsarchive/assets/css/components/textContent/textContent.css

@@ -108,7 +108,8 @@
   & blockquote + h2,
   & .highlight + h2,
   & details + h2,
-  & video + h2{
+  & video + h2
+  & table + h2 {
     margin-top: var(--m2XL);
   }
 
@@ -118,7 +119,8 @@
   & blockquote + h3,
   & .highlight + h3, 
   & details + h3,
-  & video + h3 {
+  & video + h3,
+  & table + h2 {
     margin-top: var(--mXL);
   }
 
@@ -195,14 +197,19 @@
     margin-bottom: var(--mM);
   }
 
-  & pre{
-    padding:0.8rem;
+  & pre {
+    padding: 1.5rem;
     overflow-x: scroll;
   }
 
+  & :not(pre) > code {
+    padding: 0.2em 0.4em;
+    border-radius: 0.3em;
+  }
+
   & code {
     background-color: var(--colorBlack200);
-    font-size: 0.95em;
+    font-size: 0.9em;
   }
 
   & button {

themes/opentermsarchive/assets/css/elements/table.css

@@ -1,30 +1,29 @@
 table {
   border-collapse: collapse;
   width: 100%;
+  margin-bottom: var(--mM);
 
   & thead {
     & tr {
+
       & th {
-        padding: var(--pXS) var(--pM);
-        border-bottom: 1px solid var(--colorBlack300);
-        border-right: 1px solid var(--colorBlack300);
+        text-align: left;
+        border: 1px solid var(--colorBlack300);
+        padding: var(--pXS) var(--pS);
         background-color: var(--colorBlack200);
-
-        &:last-child {
-          border-right: 1px solid var(--colorBlack200);
-        }
-        &:first-child {
-          border-left: 1px solid var(--colorBlack200);
-        }
       }
     }
   }
   & tbody {
     & tr {
       & td {
-        padding: var(--pXS) var(--pM);
-        border: 1px solid var(--colorBlack200);
+        padding: var(--pXS) var(--pS);
+        border: 1px solid var(--colorBlack300);
       }
     }
+
+    & tr:nth-child(2n) {
+      background-color: rgb(246, 248, 250);
+    }
   }
 }