From f3a8fb90cb01aa8a5015c262b945e52c5990a8a7 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 23 Aug 2026 15:34:18 +0000 Subject: [PATCH] =?UTF-8?q?docs(ui):=20tags=20IS=20read=20from=20src/docs?= =?UTF-8?q?=20frontmatter=20=E2=80=94=20correct=20the=20stale=20callout?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #10483 added an interim warn callout stating that `tags` cannot be set from a `src/docs/*.md` file. #10976 has since taught the collector to read it, so every sentence of that callout is now false and the page steers authors away from the path that works. Three sites in content/docs/ui/doc-pages.mdx, all verified against the merged collector rather than transcribed from the filing card: - the warn callout: replaced (not deleted — leaving nothing swaps one false statement for no steer at all) with the two accepted YAML spellings, the reported-not-dropped behaviour of anything else, the surfaces that raise `docs/frontmatter-tags`, the locale-variant rule, and the name-convention preference that survives as a preference; - the frontmatter table row: "not read from frontmatter" becomes frontmatter `tags:`, matching the `order:` / `group:` rows above it; - the "three scalars" sentence: `tags` is a list, not a scalar. Documentation only — no source file touched. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019siH5jDmk5hrayvfyojUqR --- content/docs/ui/doc-pages.mdx | 31 +++++++++++++++++++++---------- 1 file changed, 21 insertions(+), 10 deletions(-) diff --git a/content/docs/ui/doc-pages.mdx b/content/docs/ui/doc-pages.mdx index 35a22a6a39..bc40c78265 100644 --- a/content/docs/ui/doc-pages.mdx +++ b/content/docs/ui/doc-pages.mdx @@ -205,15 +205,26 @@ deliberately gather docs another package ships. | :--- | :--- | :--- | | `order` | sort position within the group that claims the doc | frontmatter `order:` | | `group` | explicit placement — the `key` of the group this doc belongs to, used when no rule expresses it | frontmatter `group:` | -| `tags` | the operand of a group's `include: { tag }` rule | **not read from frontmatter** — see below | +| `tags` | the operand of a group's `include: { tag }` rule | frontmatter `tags:` | - -**`tags` cannot be set from a `src/docs/*.md` file today.** The frontmatter reader -extracts single-line scalars — `title`, `description`, `order`, `group` — and has no case -for a list, so a `tags:` block in a Markdown doc is not collected and the doc reaches the -resolver with no tags. The schema key and the matcher are both live, so a doc declared -programmatically in a stack's `docs` array does carry tags and does match. For the flat -Markdown path, express the grouping with a name glob instead. + +**`tags` is read from `src/docs/*.md` frontmatter**, in the two ordinary YAML sequence +spellings — inline `tags: [tutorial, beginner]`, or a block of `- item` lines under a bare +`tags:`. What is collected is what a group's `include: { tag }` rule matches against, so a +doc authored as flat Markdown and one declared programmatically in a stack's `docs` array +place themselves the same way. + +The reader is deliberately minimal and is not a YAML engine — nested or mapping items, +block scalars, and quoted items containing commas are outside it. A `tags:` in any other +spelling is **reported, not dropped**: a `docs/frontmatter-tags` warning quoting the +spelling it found, raised by `os lint`, `os validate` and `os compile` (`os build` is the +same command). `os dev` / `os serve` collect docs without linting them, so the warning +does not appear there. Tags belong to the doc rather than to one translation: a +`..md` variant that declares `tags:` raises the same rule and its tags must +move to the base file. + +Prefer a name convention (`include: "crm_guide_*"`) when one exists — that steer survives +as a preference, not as a limitation. Tags are for membership that cuts across naming. ### Identity and access @@ -300,8 +311,8 @@ the docs themselves. The two kinds have a clean split, and the direction of reference only goes one way: -- A **doc** carries the content and, optionally, three scalars that let a spine place it - (`order`, `group`, `tags`). It names no book. +- A **doc** carries the content and, optionally, the three placement keys a spine reads — + the `order` and `group` scalars and the `tags` list. It names no book. - A **book** carries the structure and names no docs — except in a `pages` override, which is the deliberate escape hatch.