Update metadata reference

content/collections/reference/metadata.md

@@ -8,7 +8,7 @@ aliases: /collections/metadata/
 
 This reference documentation details all available metadata fields that can be specified in a collection's metadata file.
 
-As an example, see the [complete metadata file](https://github.com/OpenTermsArchive/demo-declarations/blob/main/metadata.yml) of the [Demo collection](https://github.com/OpenTermsArchive/demo-declarations).
+The examples given throughout this reference can be seen in context in the [complete metadata file](https://github.com/OpenTermsArchive/demo-declarations/blob/main/metadata.yml) and rendered in the [collection page](https://opentermsarchive.org/en/collections/demo/) of the Demo collection.
 
 
 ## Fields
@@ -17,174 +17,192 @@ As an example, see the [complete metadata file](https://github.com/OpenTermsArch
     name="id"
     type="string"
     description="Unique identifier derived from name (acronyms, dash-separated)."
-    example="`pga`"
+    example="demo"
     required=true
 >}}
 
 {{< configOption
     name="name"
     type="string"
-    description="Display name of the collection (max 3 words)."
-    example="`Platform Governance Archive`"
+    description="Display name of the collection."
+    example="Demo Collection"
     required=true
 >}}
 
 {{< configOption
     name="tagline"
     type="string"
     description="Concise description of collection topic."
-    example="`Major global social media services`"
+    example="Services used by Open Terms Archive"
     required=true
 >}}
 
 {{< configOption
     name="languages"
-    type="Array of strings"
-    description="[ISO 639 language codes](https://en.wikipedia.org/wiki/ISO_639) allowed in collection."
-    example="`[en, fr, de]`"
+    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."
+    example="[en, fr, de]"
     required=true
 >}}
 
 {{< configOption
     name="jurisdictions"
-    type="Array of strings"
-    description="[ISO 3166-2 country codes](https://en.wikipedia.org/wiki/ISO_3166-2) for covered jurisdictions."
-    example="`[EU]`"
+    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."
+    example="[EU]"
     required=true
 >}}
 
 {{< configOption
     name="description"
     type="string"
-    description="Detailed description of the collection."
-    example=`The **Platform Governance Archive** (PGA) collection tracks the terms of major global social media services.
-
-This data is maintained and analysed by the [Platform Governance Archive](https://www.platformgovernancearchive.org/) at the Universität Bremen's [Center for Media Communication and Information Research (ZeMKI)](https://www.uni-bremen.de/zemki).
-
-This initiative offers researchers, journalists and citizens the tools to analyze how platforms structure and regulate communication and interaction in our societies.
-
-It also aims to promote greater transparency and accountability of these powerful digital services.`
+    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
 >}}
-  
+
 {{< configOption
     name="dataset"
-    type="url"
-    description="URL to released versions dataset."
-    example="`https://github.com/OpenTermsArchive/pga-versions/releases`"
+    type="uri"
+    description="URL to the dataset releases."
+    example="https://github.com/OpenTermsArchive/demo-versions/releases"
+    required=false
 >}}
 
 {{< configOption
     name="declarations"
-    type="url"
-    description="URL to declarations repository."
-    example="`https://github.com/OpenTermsArchive/pga-declarations`"
+    type="uri"
+    description="URL to the declarations repository."
+    example="https://github.com/OpenTermsArchive/demo-declarations"
+    required=false
 >}}
 
 {{< configOption
     name="versions"
-    type="url"
-    description="URL to versions repository."
-    example="`https://github.com/OpenTermsArchive/pga-versions`"
+    type="uri"
+    description="URL to the versions repository."
+    example="https://github.com/OpenTermsArchive/demo-versions"
+    required=false
 >}}
 
 {{< configOption
     name="snapshots"
-    type="url"
-    description="URL to snapshots repository."
-    example="`https://github.com/OpenTermsArchive/pga-snapshots`"
+    type="uri"
+    description="URL to the snapshots repository."
+    example="https://github.com/OpenTermsArchive/demo-snapshots"
+    required=false
 >}}
 
 {{< configOption
-    name="logo"
-    type="url"
-    description="URL to the collection's logo. Optimized PNG transparent image (min width 240px)."
-    example="`https://opentermsarchive.org/images/collections/pga.png`"
+    name="donations"
+    type="uri"
+    description="URL to the donations page."
+    example="https://opencollective.com/opentermsarchive"
+    required=false
 >}}
 
 {{< configOption
-    name="donations"
-    type="url"
-    description="URL to the donations page."
-    example="`https://opencollective.com/opentermsarchive`"
+    name="logo"
+    type="uri"
+    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 tracking periods objects"
-    description="Tracking periods object, see [Tracking periods](#tracking-periods) section."
+    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="array of entity objects"
-    description="Entity object, see [Entity](#entity) section."
+    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
 >}}
 
 ---
 
-### Tracking periods
+### TrackingPeriods
 
 {{< configOption
     name="startDate"
     type="date"
-    description="The date when tracking started (ISO 8601 format: YYYY-MM-DD)."
-    example="`2023-01-01`"
+    description="The date when tracking started for this period (ISO 8601 format YYYY-MM-DD)."
+    example="2023-01-01"
     required=true
 >}}
 
-{{< configOption
-    name="endDate"
-    type="date"
-    description="The date when tracking ended or will end. If not specified, tracking is ongoing."
-    example="`2024-12-31`"
->}}
-
 {{< configOption
     name="schedule"
-    type="string"
+    type="cron-expression"
     description="A [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) that defines the tracking frequency."
-    example="`0 0 * * *`"
+    example="0 0 * * *"
     required=true
 >}}
 
 {{< configOption
     name="serverLocation"
     type="string"
-    description="The geographic location of the tracking server (city name, ISO 3166-2 country code)."
-    example="`London, GB`"
+    description="The geographic location of the tracking server (city name and ISO 3166-2 country code)."
+    example="Paris, FR"
     required=true
 >}}
 
----
-
-### Entity
-
 {{< configOption
-    name="name"
-    type="string"
-    description="Name of the organization."
-    example="`Open Terms Archive`"
-    required=true
+    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."
+    example="2023-12-01"
+    required=false
 >}}
 
+
+---
+
+### Governance
+
 {{< configOption
     name="url"
-    type="url"
-    description="Website URL of the organization."
-    example="`https://opentermsarchive.org/`"
+    type="uri"
+    description="URL to the entity's website"
+    example="https://opentermsarchive.org/"
+    required=false
 >}}
 
 {{< configOption
     name="logo"
-    type="url"
-    description="URL to the organization's logo. Optimized PNG transparent image (min width 240px)."
-    example="`https://opentermsarchive.org/images/logo/logo-open-terms-archive-black.png`"
+    type="uri"
+    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"
-    type="string"
-    description="Roles of the entity within the governance, see [collection governance]({{< relref \"collections/reference/governance\" >}})."
+    type="array of strings"
+    description="Roles of the entity within the governance, see [collection governance](https://docs.opentermsarchive.org/collections/reference/governance/)"
     allowedValues="`host`, `administrator`, `curator`, `maintainer`, `sponsor`"
+    example="[host, administrator]"
     required=true
 >}}

themes/opentermsarchive/layouts/shortcodes/configOption.html

@@ -12,7 +12,14 @@
         <div class="config-option-default"><span>Default:</span>{{ .Get "default" | markdownify}}</div>
         {{ end }}
         {{ if .Get "example" }}
-        <div class="config-option-example"><span>Example:</span>{{ .Get "example" | markdownify }}</div>
+        <div class="config-option-example"><span>Example:</span>
+            {{ $example := .Get "example" }}
+            {{ if not (strings.Contains $example "\n") }}
+                <code>{{ $example | markdownify }}</code>
+            {{ else }}
+                {{ $example | markdownify }}
+            {{ end }}
+        </div>
         {{ end }}
         {{ if .Get "allowedValues" }}
         <div class="config-option-allowed-values"><span>Allowed values:</span>{{ .Get "allowedValues" | markdownify }}</div>