Skip to content

Align YAML header convention across templates, editor-manual, and DOCS/ #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
MatMatt wants to merge 2 commits into from
Closed

Align YAML header convention across templates, editor-manual, and DOCS/ #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3c77788
fix: align YAML header convention across templates and editor-manual
MatMatt Jul 5, 2026
9ddbfcb
fix: correct date format in Small_Landscape_Features_2021_PUM_v1.qmd …
MatMatt Jul 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion DOCS/High_Resolution_Layer/Small_Landscape_Features_2021_PUM_v1.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "High Resolution Layer Small Landscape Features 2021 – Product User Manual"
subtitle: "Copernicus Land Monitoring Service"
date: "16/09/2025"
date: '2025-09-16'
version: 1.0

category: products
Expand Down
38 changes: 24 additions & 14 deletions DOCS/guidelines/editor-manual_v1.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,34 +71,44 @@ Migrating an existing `.docx`? See the Migration Guide [TBD link].

# The YAML Header

If you copied a template, the header is pre-filled - just update `title`, `subtitle`, `date`, and `product-name`.
If you copied a template, the header is pre-filled — update `title`, `subtitle`, `date`, `category`, and `version`.

## Required fields

```yaml
---
title: "HRL Forest"
subtitle: "High Resolution Layer - Forest Type"
date: "2026-01-27"
product-name: "HRL Forest"
category: products
date: '2026-01-27'
subtitle: Copernicus Land Monitoring Service
title: HRL Forest - Product User Manual
toc: true
toc-depth: 3
toc-title: Content
version: 1.0
Comment on lines +84 to +87

@chatgpt-codex-connector chatgpt-codex-connector Bot Jul 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep ignored fields out of required YAML

For documents created from this guide/template, these fields won't behave as required author metadata: I checked the publish path and .github/scripts/build/build-docs.sh runs strip_unknown_frontmatter.py, whose allowlist/comment says toc/toc-depth/toc-title are stripped, and then fill_version.py rewrites version from .llm_cache/versions.json or {major}.0.0 from the _vN.qmd name; the PR validator also explicitly does not check these fields. An editor following this will think changing toc-title or version controls the published document, but the build ignores/overwrites those values, leaving source metadata stale and the guide contradicted by the workflow.

Useful? React with 👍 / 👎.

---
```

- `title` - short product name, appears as the document title
- `subtitle` - full product name or document type description
- `date` - publication or last-updated date in ISO format
- `product-name` - used internally for metadata and indexing
- `category` — one of `products`, `guidelines`, or `non-browsable`. Determines where the document appears in the library.
- `date` — publication or last-updated date in ISO format (`YYYY-MM-DD`).
- `subtitle` — typically `Copernicus Land Monitoring Service` for product documents.
- `title` — the document title, including the product name and document type (e.g. "– Product User Manual").
- `toc` — always `true` for published documents.
- `toc-depth` — always `3`.
- `toc-title` — always `Content`.
- `version` — the current published version (e.g. `1.0`, `2.3`). This number appears in the document header and must match the filename suffix.

## Optional fields

- `template-version` - records which template version was used as the starting point. Set automatically when copying a template; don't edit it manually.
- `author` — document author or organisation (e.g. `Copernicus Land Monitoring Service`).
- `description` — a short summary of the document, used for SEO and library listings.
- `editor` — Quarto editor settings (e.g. `markdown: wrap: 72`).
- `template-version` — records which template version was used as the starting point. Set automatically when copying a template; don't edit it manually.

## System-managed fields

Leave these out of your YAML header entirely - the publishing system handles them:
Leave these out of your YAML header entirely — the publishing system handles them:

- `keywords` - AI-generated at publish time based on document content. Anything you add gets overwritten.
- `version` - carried by the filename suffix, not the YAML. No version field belongs in the header.
- `keywords` — AI-generated at publish time based on document content. Anything you add gets overwritten.


# Writing Content
Expand Down Expand Up @@ -228,7 +238,7 @@ Your work lives in `DOCS/` directly: one `.qmd` file per document, plus a matchi

## The version suffix

The `_v<N>` suffix in the filename is the major version - the only version number you control. Minor and patch versions are assigned automatically by AI at library release time based on the scope of changes: small corrections get a patch bump (`2.3.5 → 2.3.6`), new or revised sections get a minor bump (`2.3.0 → 2.4.0`). A new file `CLMS_HRL-Forest_PUM_v3.qmd` starts at `3.0.0` at its first release. You never set a version number in YAML.
The `_v<N>` suffix in the filename and the `version` field in the YAML header should match — both carry the major version. Minor and patch versions are assigned automatically by AI at library release time based on the scope of changes: small corrections get a patch bump (`2.3.5 → 2.3.6`), new or revised sections get a minor bump (`2.3.0 → 2.4.0`). A new file `CLMS_HRL-Forest_PUM_v3.qmd` starts with `version: 3.0` in YAML and `3.0.0` at its first release.

## When to create a new major version

Expand Down
16 changes: 9 additions & 7 deletions _meta/templates/CLMS_ATBD_Template.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
---
title: "Product SHORT NAME ALGORITHM THEORETICAL BASIS DOCUMENT (ATBD)"
subtitle: "ATBD Copernicus Land Monitoring Service -- Product full name"
date: "2022-10-06"
version: Issue x.y (“(x) version of the document” + “.”+ “(y) version of the document
update”)
category: products
date: '2022-10-06'
subtitle: Copernicus Land Monitoring Service
title: Product short name – Algorithm Theoretical Basis Document (ATBD)
toc: true
toc-depth: 3
toc-title: Content
version: 1.0
template-version: 1.0.0
product-name: Product Name
description: "Product DESCRIPTION"
description: Product DESCRIPTION

format:
html:
Expand Down
16 changes: 9 additions & 7 deletions _meta/templates/CLMS_PUM_Template.qmd
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
---
title: "Product full name – Product User Manual (PUM)"
subtitle: "Copernicus Land Monitoring Service"
date: "2022-10-06"
version: Issue x.y (“(x) version of the document” + “.”+ “(y) version of the document
update”) (first published version must start with 1.0)
category: products
date: '2022-10-06'
subtitle: Copernicus Land Monitoring Service
title: Product full name – Product User Manual (PUM)
toc: true
toc-depth: 3
toc-title: Content
version: 1.0
template-version: 1.0.0
product-name: Product Name
description: "Product DESCRIPTION"
description: Product DESCRIPTION

format:
html:
Expand Down