Liking cljdoc? Tell your friends :D

com.blockether.vis.internal.docs.core

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.

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.
raw docstring

com.blockether.vis.internal.docs.corpus

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.
raw docstring

cljdoc builds & hosts documentation for Clojure/Script libraries

Keyboard shortcuts
Ctrl+kJump to recent docs
Move to previous article
Move to next article
Ctrl+/Jump to the search field
× close