the ??? census marker flags keywords that work by design #2

closed cmc opened this on 2026-08-25 16:23 UTC

Discussion

cmc 2026-08-25 16:23 UTC

The census legend says ??? marks "a name the implementation does not recognize at all", and docs/guide/09-auditing.org calls these "the dangerous ones — not \known unsupported\ but unknown". orgo audit docs reports one:

??? LEDE                                   14      14  guide/01-cli.org:3

#+LEDE: is not unknown. It is:

  • consumed by docs/templates/base.html:33, as {{ page.keywords.lede }}
  • styled by themes/docs.css:104
  • documented at docs/guide/02-configuration.org:70 as a feature of the docs theme

So the audit flags a documented, working, first-class feature as a blind spot, on orgo's own documentation.

The cause is that ??? means "not in KNOWN_KEYWORDS", but an unlisted keyword is not a gap — reaching templates as page.keywords.<name> is the designed behaviour, and the README says so: "metadata orgo has never heard of still reaches your layout." Every unknown keyword works. That makes ??? on a keyword a statement about orgo's source, not about the corpus.

That is not the same as saying the census has no value. Knowing which of your keywords have dedicated handling and which rely on pass-through is worth reporting — it is the wording and the framing that are wrong, not the data.

Options:

  1. Keep the marker, change what it claims. Something like — for "no dedicated handling, reaches templates" and reserve ??? for names where that fallback does not apply. Needs a list of the latter; there may be none for keywords.
  2. Add the theme keywords orgo ships (LEDE) to KNOWN_KEYWORDS, alongside SLUG/DRAFT/TEMPLATE, which are there for exactly this reason — the comment at src/audit.rs:80 says leaving them out "reported the corpus's most-used keyword as unrecognized". This fixes the instance and leaves the general framing as is.
  3. Drop ??? for the keyword census.

Option 2 is the smallest and matches an existing precedent; option 1 is the one that makes the legend true. #28 took the equivalent decision for the block census, where every name renders and none is a blind spot.

closed by commit 70dc5827f4 by cmc: audit: an unlisted keyword is pass-through, not a blind spot (#2)

2026-08-30 06:55 UTC