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

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 browser tab and the page itself must never disagree about a page's name. The sidebar shows the same title, or a shorter :label inside a group whose name says the rest (HTTP API under Basics, Sessions under Feature APIs). 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.
• The :nav of vis-docs/site.edn is the reading order, in modules: Intro (Rationale, Getting started, Running a gateway and Reporting a bug, the :intro? module), Concepts (one page for each feature), Programmatic access (the Basics and Feature APIs groups), Extensions and Reference. A Concepts page X that a program can drive has one page X-api in Feature APIs, and X links it. On the public site, the Extension Center link ends the module that :extension-center names.
• PAIRED VARIANTS: an X-api page gives each example twice. A <div data-variant="python"> block comes first, and a <div data-variant="http"> block follows it at once. Each tag and its </div> stand alone on their lines, with a blank line between the tag and the Markdown, or commonmark does not render that Markdown. A block holds no heading, so both variants share one table of contents. The site shows one variant and a switch (see variant-html). doc gives the agent only the Python blocks (see doc-corpus/variant-text). Only HTTP blocks and the http-api page name gateway routes.
• A page outside the intro module documents a feature, so its FIRST ## is When to use: two or more problems a reader brings, each tied to the part of the page that solves it, and the page to read instead when a neighbouring feature fits better. It follows the lead and never precedes it, because the lead's first paragraph is also the page's apropos row.
• ## 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.
• PLAIN ENGLISH: prose follows ASD-STE100 Simplified Technical English, so a reader with basic English, or a translation tool, gets the same meaning. No sentence runs past 25 words and no paragraph past six sentences, where a code span counts as one word. A clause ends with a full stop, never with a semicolon. A hard word gives way to the simpler word that test-prose/simpler-words names: use, not utilize.

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 variants] :as _page}
           mode)

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