docs-frontmatter

Documentation frontmatter conventions

Apply when creating or editing .md pages under any spaces[].content_root declared by the applicable docs profile. Three conventions, all in the page's YAML frontmatter, applied in the same pass: changelog entries, self-hosted-docs owners, and the core metadata fields.

1. Changelog (changed existing pages only)

For every changed existing page (NOT brand-new pages — first publish uses the published timestamp instead), prepend a changelog: entry dated today:

1. Get today's date: run date +%F (yields YYYY-MM-DD, two-digit month).
2. Prepend the entry as the first list item under changelog: (newest first):

   changelog:
     - <today> <change description>
     - <older entries unchanged>
   

3. Keep each entry — including the leading - and date — within 200 characters.
4. Write the description per the guidelines reference. The most-missed rule: the period rule — verify before finalizing each entry:
   • complete sentence → ends with a period;
   • phrase / fragment → no period. Also: past tense; active verbs; meaningful and customer-facing; no "documented"; don't overuse "added"; no section titles; never expose "hidden"; no short forms ("info", "max"); single paragraph.

Full rules and worked examples (source of truth): ${CLAUDE_PLUGIN_ROOT}/references/docs-profiles/changelog-guidelines.md

2. Owners (changed self-hosted pages only)

For changed pages in a space listed in frontmatter.owners_spaces that have — or should have — an owners: block, ensure every required ID is present. Union only — never remove existing owners.

1. Read the required IDs (ignore # comments and blank lines): ${CLAUDE_PLUGIN_ROOT}/references/docs-profiles/default-owners.txt
2. If the page has no owners: block but one is warranted (most self-hosted pages carry owners), add one containing the required IDs.
3. If an owners: block exists, add any required IDs that are missing and leave all existing owners in place.