com.blockether.vis.internal.docs.core — com.blockether/vis 0.2.3

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.

build-site! clj

(build-site! out-dir)

(build-site! out-dir {:keys [public?]})

Render the docs and shared assets to a static bundle. :public? adds same-origin Extension Center navigation; the catalog is not a document or part of live docs.

collect clj

(collect)

The whole site: every documentation record the corpus read, rendered to HTML with anchors and a table of contents, pages in manifest order within their sections. Rendered ONCE — the records are read at load and a distribution's documents cannot change under a running process, so there is nothing to invalidate and no freshness check to pay for.

handle clj

(handle {:keys [uri headers] :or {uri ""}})

Ring handler for the docs site. Returns nil for paths it does not own (so the gateway can fall through). Owns /docs, /docs/<slug>, /docs/assets/**.

md->html clj

(md->html md)

page-html clj

(page-html {:keys [site] :as site-data}
           {:keys [slug title html toc] :as _page}
           mode)

Full HTML document for one page. mode ∈ #{:static :live}.