Embedded documentation from the explicit records listed by
META-INF/vis/manifest.edn.
Each documentation record names one exact Markdown resource; no classpath
enumeration or alternate docs manifest exists. The same records feed the live
docs site and the sandbox doc/apropos surface, and how a page is TITLED,
grouped and ordered — everything only this site reads — is vis-docs/site.edn.
THE PAGE CONTRACT — one canonical shape for every page, enforced by
docs-test/docs-page-canon-test:
:title in vis-docs/site.edn IS the page's # H1, spelled
identically, on the FIRST line of the file: the sidebar, the browser tab
and the page itself must never disagree about a page's name. index.md is
the ONE exception — its title is rendered from the site navigation, so it
carries no # at all.##: what this page
covers, so a reader who stops there still knows what they found.## and ### only. A deeper heading gets no id and no on-this-page
entry (see anchors+toc), so nothing — not even this page — can link to it.page.md#anchor link
resolves against the TARGET page's own toc.bash, clojure, edn,
ini, java, json, markdown, python, text, toml, xml, yaml.index.md is the MAP: it links every other page under ## Learn more,
with that page's title as the link text, so a page nobody can reach from
the landing page does not exist for a reader.## of every page is See also — two or more sibling pages, each
with the reason to follow it. That web is what keeps ONE topic in ONE page:
a topic explained twice is a cross-link somebody never wrote.:blurb in vis-docs/site.edn, the one sentence the
sidebar and the index cards show.A; B; C, first … then … finally): write it as the list it is.One renderer, two outputs:
build-site! writes a static, themed HTML bundle for the public Worker.handle serves the same pages live (HTMX nav), mountable on the gateway
via its :gateway.slot/http-routes slot.Markdown → HTML uses commonmark-java. Static and live pages share a responsive layout with navigation, article content and a table of contents.
Embedded documentation from the explicit records listed by
`META-INF/vis/manifest.edn`.
Each documentation record names one exact Markdown resource; no classpath
enumeration or alternate docs manifest exists. The same records feed the live
docs site and the sandbox `doc`/`apropos` surface, and how a page is TITLED,
grouped and ordered — everything only this site reads — is `vis-docs/site.edn`.
THE PAGE CONTRACT — one canonical shape for every page, enforced by
`docs-test/docs-page-canon-test`:
* The `:title` in `vis-docs/site.edn` IS the page's `# H1`, spelled
identically, on the FIRST line of the file: the sidebar, the browser tab
and the page itself must never disagree about a page's name. `index.md` is
the ONE exception — its title is rendered from the site navigation, so it
carries no `#` at all.
* Under the H1 comes a LEAD paragraph, before the first `##`: what this page
covers, so a reader who stops there still knows what they found.
* `##` and `###` only. A deeper heading gets no `id` and no on-this-page
entry (see `anchors+toc`), so nothing — not even this page — can link to it.
* Anchors are unique within a page, and every relative `page.md#anchor` link
resolves against the TARGET page's own toc.
* Every fenced block declares a language, one of `bash`, `clojure`, `edn`,
`ini`, `java`, `json`, `markdown`, `python`, `text`, `toml`, `xml`, `yaml`.
* `index.md` is the MAP: it links every other page under `## Learn more`,
with that page's title as the link text, so a page nobody can reach from
the landing page does not exist for a reader.
* The last `##` of every page is `See also` — two or more sibling pages, each
with the reason to follow it. That web is what keeps ONE topic in ONE page:
a topic explained twice is a cross-link somebody never wrote.
* Every page carries a `:blurb` in `vis-docs/site.edn`, the one sentence the
sidebar and the index cards show.
* NO WALL OF TEXT: one paragraph — or one list item with its continuation
lines — stays under 800 characters. Past that the reader is handed a
table or a list as prose, and the structure is usually already in the
sentence (`A; B; C`, `first … then … finally`): write it as the list it is.
One renderer, two outputs:
* `build-site!` writes a static, themed HTML bundle for the public Worker.
* `handle` serves the same pages live (HTMX nav), mountable on the gateway
via its `:gateway.slot/http-routes` slot.
Markdown → HTML uses commonmark-java. Static and live pages share a
responsive layout with navigation, article content and a table of contents.The one ordered document corpus behind apropos(pattern) and doc(name).
Static resources and live sources contribute the same closed record shape. Invalid static records fail at load; invalid dynamic records are logged and dropped.
entries is the whole corpus in source order, deduplicated by EXACT name; pages
is the documentation subset the docs site renders. apropos applies one regular
expression to record names and preserves corpus order — there is no ranking,
tokenization, search index or classpath discovery. doc retrieves the same record
by name and prints its whole text.
The one ordered document corpus behind `apropos(pattern)` and `doc(name)`. Static resources and live sources contribute the same closed record shape. Invalid static records fail at load; invalid dynamic records are logged and dropped. `entries` is the whole corpus in source order, deduplicated by EXACT name; `pages` is the documentation subset the docs site renders. `apropos` applies one regular expression to record names and preserves corpus order — there is no ranking, tokenization, search index or classpath discovery. `doc` retrieves the same record by name and prints its whole text.
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 |