Align YAML header convention across templates, editor-manual, and DOCS/#39
Align YAML header convention across templates, editor-manual, and DOCS/#39MatMatt wants to merge 2 commits into
Conversation
Resolve conflicts between three sources that defined different YAML header formats. Standardize on the convention actually used by all 25 DOCS/ files on main: no double quotes, category first, toc group present, version in YAML (not forbidden). - editor-manual: update YAML example, move version from forbidden to required, add category/toc fields, remove product-name - PUM/ATBD templates: strip double quotes, add missing fields, remove product-name, clean up placeholder text
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3c77788312
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| toc: true | ||
| toc-depth: 3 | ||
| toc-title: Content | ||
| version: 1.0 |
There was a problem hiding this comment.
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 👍 / 👎.
1 participant
Problem
The YAML header convention was inconsistent across three sources:
_meta/templates/) used double quotes,product-name, aformat:block, placeholderversiontextversionin YAML, requiredproduct-name, omittedcategory/toc/toc-depth/toc-titlecategoryfirst,tocgroup,versionpresentChanges
editor-manual_v1.qmdversionmoved from forbidden to requiredcategory,toc,toc-depth,toc-titledocumentedproduct-nameremovedTemplates (PUM + ATBD)
category/toc/version, removedproduct-nameNo DOCS/ content files touched — all 25 existing documents already follow this convention.