Generated component docstrings (codegen/plan.clj, component-docstring /
prop-lines) are consumed by two audiences with different rendering rules:
clojure.repl/doc and editor hovers show them as raw text, while cljdoc
renders them as Markdown. The prop list was authored for the first audience —
one prop per source line, 2-space indent — which cljdoc's Markdown renderer
collapses: single newlines become spaces, so every prop ran together into one
wall of text. Two angle-bracket hazards compounded it: descriptions carry literal
<code>…</code> from Mantine's docgen (2428 occurrences), and prop type names
carry TS-generic brackets (Omit<PortalProps, "children">, Partial<Record<…>>)
— both look like HTML tags to cljdoc's sanitizer and get mangled or dropped.
Emit each prop as a Markdown bullet list item, so the fix reads well in both audiences:
- **{name}** `{type}`{ **(required)**}{ _(default `{d}`)_} — {description}
|, ", and
TS-generic <…> are all literal — the type-name hazard is neutralized
structurally, not per-token.squash-ws collapse. An audit of all 4,530 non-empty
descriptions found zero prose hazards for _ * < > | (they only ever appear
inside <code> spans or as ->/=> operators), the two [text](url)
sequences render as intended links, and multi-line descriptions with interior
- lines are flattened by squash-ws so they never become stray lists.<code>…</code> → backticks. The only active backticks in the output are
therefore the ones we emit from balanced <code> pairs — code spans can never
be left open. This kills the one description that actually broke rendering
(DateTimePicker.defaultTimeValue, an upstream stray-backtick typo) and any
future one of its kind.The change is produced through codegen, never hand-edited into generated
files; docgen.json itself stays a verbatim upstream copy (codegen/extract.clj)
and is not patched.
docgen.json. Rejected: docgen.json is a verbatim
copy of Mantine's docgen output, re-extracted on every anchor bump, so a manual
patch violates that invariant and is clobbered by the next bb extract. The
escape-then-convert rule fixes the symptom in codegen where it belongs.Can you improve this documentation?Edit on GitHub
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |