Generated component docstrings (codegen/plan.clj, component-docstring /
prop-lines) have 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), and cljdoc's Markdown renderer
collapses that layout: single newlines become spaces, so every prop ran together into one
wall of text. Two angle-bracket hazards made it worse. 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 output reads well for both audiences:
- **{name}** `{type}`{ **(required)**}{ _(default `{d}`)_} — {description}
|, ", and
TS-generic <…> are all literal. This removes the type-name hazard
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 squash-ws flattens multi-line
descriptions with interior - lines 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, so a code span can never
be left open. This fixes the one description that broke rendering
(DateTimePicker.defaultTimeValue, an upstream stray-backtick typo) and any
future one of its kind.Codegen produces the change; it is 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 the next bb extract overwrites it. 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 |