Documentation HTML rendering and authoring

For contributors maintaining product and implementation documentation. Every published page is HTML, with shared navigation, search and theme controls. The source format is chosen for the document: native HTML for visual implementation/design documents, Markdown for short usage and reference text.

Rendering paths#

Prefer HTML fragments for implementation documents that should share the site layout. A standalone document is appropriate when its visualization needs an independent viewport. The iframe separates layout; it is not a security sandbox for untrusted scripts.

Implementation ownership#

See the builder source and serving implementation.

Reading and visual design#

Start with the document's question, audience, scope and implementation boundary. Explain the public entry and data/state flow before implementation details. Use a source map for ownership, a diagram for control or data flow, and a final implementation-status section for remaining work and evidence gaps.

Use the existing --bg, --bg-code, --tx, --tx-soft, --acc and --bd theme variables in fragments. The site uses the Web application's warm neutral palette and orange accent. Do not repeat a fixed light-only palette inside an article.

Use semantic headings with stable id values so HTML sections appear in the page navigation. Tables need a locally scrollable container when their columns cannot fit a narrow screen. Diagrams need an accessible title and description. Native disclosure controls can separate detailed evidence from the main explanation. Keyboard focus, reduced motion and mobile reading are part of document acceptance.

The site theme preference is stored as op-docs-theme; documentThemeChange is dispatched on the site window when the effective palette changes. An iframe has its own document and does not automatically receive that event. Keep a standalone page's theme behavior explicit or use a fragment to inherit the shared theme.

The shared reader keeps wide tables in keyboard-accessible horizontal scroll regions and preserves a readable column width. Standalone HTML receives the same table support plus diagram scroll regions and an opaque fallback canvas when the source defines no background. These helpers preserve the document content and its own palette; they do not certify the implementation described by a page.

Navigation and bilingual sources#

The nine tabs are start, install, capabilities, interfaces, models, integrations, server, reference and virtual design. Design sources stay under docs/reference/design/; there is no docs/design/ source directory.

TAB_SECTIONS declares product reading order; PAGE_ORDER controls explicit page ordering. Remaining pages are grouped by directory. Directory headings use configured labels or README titles. Do not assume that the sidebar is a literal filesystem tree or that all pages are ordered by filename.

English is the default. topic.zh.md pairs with topic.md, and topic.zh.html pairs with topic.html. The Chinese source is attached to the English page and reached through the language control, rather than appearing as a second sidebar entry. Update both members when changing a bilingual topic.

The builder supports existing same-name Markdown/HTML companions by assigning the HTML companion a .viz.html output. A relative topic.md link targets the text output; a relative topic.html link targets the HTML companion at topic.viz.html, preserving its section anchor. The Chinese HTML companion uses topic.zh.viz.html, while the Chinese Markdown output keeps topic.zh.html; language controls use these distinct outputs. This compatibility behavior does not justify maintaining two copies of the same explanation. Compare content before consolidating: retain distinct diagrams and evidence and update their incoming links.

Generated output and static-only folders are excluded from page discovery. docs/superpowers/ is explicitly excluded. A leading underscore alone is not an exclusion rule: the proactive research archive currently remains discoverable.

Build and serving#

python -m scripts.docs_site.build
python -m scripts.docs_site.checklinks
python -m scripts.docs_site.checklang
python -m scripts.docs_site.check_landing

Run these commands from the repository root with the documentation dependencies available. The contributor guide lists the uv run environment. The link checker reads built HTML, so rebuild before checking.

checklang currently checks default product Markdown only; it excludes the design directory and does not scan HTML sources. A pass does not establish bilingual compliance for all design pages. Review the language and counterpart of revised HTML separately.

The build regenerates code-derived CLI/config/provider reference pages, writes docs/_site.tmp/, and replaces docs/_site/ after successful rendering. docs/_site/ is ignored by Git. Files under docs/_static_root/ are published at the site root without entering navigation or search.

A source checkout serves its docs/_site/. An installed runtime can serve bundled documentation under the Server's _frontend/docs/; rebuilding a different checkout does not update that bundle. Compare the served page with the expected output before claiming local acceptance. Default local verification uses http://localhost:18100/docs/. Completed application updates use scripts/refresh-local-app.sh under the repository's local-App rules.

The source worker checks for a rebuild when registering documentation routes; ordinary HTTP reads do not scan or rebuild the source tree. There is no continuous watch mode.

Design alternatives#

The existing design chooses the in-repository Python renderer to preserve native HTML/SVG/script content and integrate with the single-port worker. The alternative comparison concerns this project's requirements, not a current capability survey of external products.

The renderer uses markdown-it-py, mdit-py-plugins and Pygments. It produces static assets without a client framework or an editor/CMS. A framework migration is outside this documentation update.

Reader navigation

Grouped navigation uses one continuous dashed indicator from the first row to the selected row, with a rounded end aligned to the label center. The indicator changes height when navigating within a group. Pointer hover and keyboard focus preview a separate neutral indicator without changing the selected page. Keyboard focus is shown by a text underline and a subtle row background, not a large outline around the entire sidebar row. The section index uses the same indicator behavior. Filtering, wrapped labels, language changes and resizing recompute indicator geometry. The root overview has explicit English and Chinese labels rather than a filename-derived label.

The reader retains the nine categories and static HTML routing. The layout places category tabs above grouped page navigation, a central reading column, and a section index. On narrow screens the page index becomes a drawer and the section index remains available through an expandable reading-progress control.

Interaction references are Rare UI Hook Sidebar, Scroll Progress, and Code Block. Their grouped active indicators, progress with section links, and labelled copyable code inform an independent implementation in the existing static assets. No Rare UI source or React dependency is included; component source reuse has separate licensing requirements. Decorative orb, proximity scaling and gooey navigation are excluded because stable text targets matter for document reading.

The visual tokens retain the application palette: paper #faf9f5, sidebar #f5f4ed, code #f0eee6, text #3d3d3a and accent #b8651f, with existing dark equivalents. Local Inter is used for navigation and prose; system monospace is used for code. All content is left aligned. Groups use connecting indicators and sentence-case titles; the article remains the primary reading surface.

Scrolling updates the active heading and progress in the current scroll container. Opening the progress disclosure exposes real anchor links; selecting a heading closes it and moves to that heading. Escape and outside clicks dismiss it. SPA navigation rebuilds heading references and resets progress. Fullscreen uses the content scroller. Standalone iframe content owns its internal reading state, so the outer progress control is hidden there. Resizing and article-size changes recompute the state; reduced-motion preferences disable animated scrolling.

Code blocks receive a language header and an always available copy button outside horizontal overflow. Copy reads only code text, exposes success or failure, and preserves highlighting. Existing authored copy controls are preserved. Search, theme, language pairs, relative links and generated reference pages retain their existing contracts. No external runtime requests are added.

Acceptance covers deep links, category and page changes, browser history, language switching, keyboard disclosure dismissal, code copying, long and short articles, fullscreen, mobile overflow and iframe isolation. Implementation evidence remains pending until independent review and build, link, language, landing, repository and browser verification pass.

Design information architecture

The catalog uses three levels: area, module, page. Seven top-level areas contain architecture, agents and workflows, context and memory, interfaces, models and external connections, security and engineering, and supporting material. Modules expand inside their area rather than appearing as a flat list. Architecture lists its entry pages directly without a redundant overview level.

Each page belongs to one module. Direct loads and in-site navigation expand every ancestor of the current page. Filtering matches page and category names, preserves matching ancestor paths and temporarily expands them; clearing restores the prior state at every level. Native details and summary controls support keyboard operation. New pages remain visible in an Uncategorized area. Both languages share the hierarchy, order and output mapping. The landing page uses the same seven areas.

Navigation changes preserve detailed content, diagrams, URLs and implementation evidence. Prototypes, implementation records and research remain distinct under Supporting material and do not imply implemented product behavior. Acceptance covers complete unique membership, seven top-level entries, ancestor expansion and filter restoration, bilingual and mobile behavior, and compatibility with other product tabs.

Sidebar visual hierarchy uses 13px area labels, 12px module labels and 13px page labels. Modules add only 12px of indentation; pages align consistently and wrap naturally. Counts appear at the area level only. Selection uses the continuous indicator and accent text without a background fill; hovering page links or category headings also keeps the background transparent; keyboard focus uses a separate inset ring without underlining multiline labels. Redundant vertical borders are removed while the continuous active-group indicator remains. These rules apply only to design navigation and support both themes and narrow screens.

Canonical documents and stable URLs

Each topic has one maintained source. Consolidation retains unique diagrams, constraints, implementation status and acceptance evidence; complementary usage guides and API references remain separate. Topic filenames use descriptive lowercase hyphenated words, without dates, TODO or PROBLEM prefixes. Deferred proposals include their status in the title.

A topic’s rationale and model-selection analysis belong beside its design contract, not in a second maintained document. Runtime combines its introduction and lifecycle choices; the DAG design includes model alternatives and their disposition. Consolidation resolves superseded claims against the current schema, retains unique constraints and reference comparisons, and preserves every retired heading through section anchors. Usage/API guides remain separate because they answer a different reader question.

The builder reads an explicit map of retired output paths to canonical pages. It emits redirect-only HTML outside navigation, search and sitemap, preserving query strings and section fragments. A same-origin external script executes redirects under the worker’s CSP; inline redirect scripts are not permitted. SPA navigation performs a full load for redirect-only documents, explicitly reloading when browser history has already selected that URL. Redirect targets must exist and aliases must not replace real pages or point to another alias; invalid mappings abort the atomic build. Existing language-specific URLs retain their language when a counterpart exists. Standalone raw and Markdown/HTML companion URLs are included in the map.

Acceptance: discover each surviving source exactly once, resolve every old URL directly to an existing canonical output, retain unique content during merges, pass links and language checks, and verify navigation and redirect behavior on the default local docs mount. Page consolidation does not change runtime behavior or certify deferred designs as implemented.

Names inside a subsystem directory omit a redundant subsystem prefix: context/statistics.html, memory/editor.html and runtime/dag/layout.html. Page titles likewise use local topics such as Composition, Compaction and Statistics; breadcrumbs, the parent group and opening prose provide scope. Keep established technical terms and cross-subsystem names where removing a word would change meaning. Use an explicit diagram qualifier when a text page already owns the shorter output name. Preserve old heading IDs and flatten old URL aliases directly to the latest output.

Implementation status#

Language consistency

Every authored document has full English and Chinese bodies. The unsuffixed source is English and the .zh source is Chinese. Translation retains complete explanations, diagrams, code, identifiers, links and implementation-status boundaries; headings and visible diagram labels follow the document language. Sidebar, breadcrumbs, previous/next links and search use the corresponding localized title and destination. Language checks cover design notes, HTML, SVG, and accessible labels, preserving technical identifiers and compatibility anchors. Interactive pages also require checks of script-generated visible text. Both language versions of the feature matrix use the same numeric, detail-row, and chart-consistency checks.

Navigation names

Navigation names are short noun phrases, separate from the full descriptive heading in the document. English prefers two or three words, permits one when unambiguous, and has a hard limit of four words and 26 characters. Chinese names have at most 12 characters. Use sentence case, preserving proper nouns and technical acronyms. Remove redundant product or parent-category prefixes, completeness claims, code signatures and parenthetical explanations. Use diagram, comparison and prototype as consistent noun modifiers when those distinctions are needed. Names must remain unique within the same leaf section. One bilingual catalogue, keyed by canonical source path, supplies navigation, breadcrumbs, search and previous/next labels. Generated reference names remain code-derived. Keep document bodies, URLs, anchors, hierarchy and RareUI styles unchanged; verify that labels fit the available sidebar width without clipping or ellipsis.

Documentation completeness

The repository README introduces the project, verified entry commands, examples and citation; its Chinese counterpart follows the same structure. The documentation homepage directs readers to the nine topic tabs instead of repeating the repository introduction. Reference overviews link to both task guides and generated command, configuration and provider details. Existing document URLs and compatibility anchors remain stable.

Reference generation emits English and Chinese pairs from the same argparse tree, settings schema and provider manifests. Command names, flags, keys, defaults and protocol values stay exact. A source-string translation catalogue supplies Chinese descriptions and headings; missing translations fail generation rather than silently showing English prose. Both languages traverse every command depth, share the same option inventory, and are written only when content changes. Removed generated command pages are removed in both languages. Translation data contains no credentials; generation reads schema defaults, never user configuration. Generators complete before site discovery; failures abort the build. Navigation uses concise noun phrases, including generated reference pages, without changing the RareUI presentation.

Acceptance covers all reference pairs, recursive command/options parity, missing-translation failures, idempotence, stale-page removal, homepage language links, short names, site links, language checks and visible language switching on the default local instance.

Theme preference

The shared shell supports system, light and dark preferences. Missing or invalid stored values resolve to system; existing explicit light/dark preferences remain valid and can be changed back to system in the header menu. The effective palette follows prefers-color-scheme changes while system is selected. A cross-tab storage event updates the preference without writing it back. Storage failures preserve usable in-memory controls and system following.

A synchronous same-origin theme.js in the head applies the palette before the body is parsed, including the browser color-scheme and syntax-highlighting styles. This replaces the inline bootstrap rejected by the local script-src self policy; the policy is not weakened. One controller owns initial state, media listeners and the three-option accessible, localized menu. SPA navigation retains the controller and theme preference. Changes notify existing documentThemeChange consumers on the document window. The controller does not change independent standalone iframe documents or the operating system appearance setting.

Acceptance covers first load in both system palettes, live system changes without reload, explicit overrides and return to system, legacy/invalid preferences, unavailable storage, cross-tab updates, menu keyboard/language behavior, code colors and SPA navigation. Browser media emulation is temporary and restored after verification; the local docs preference is left on system as requested.

Heading hierarchy

Pages without an on-page table of contents hide the empty right column and give that space to the article. The fullscreen control stays at the right edge. Pages with a table of contents retain the column; in-site navigation updates this layout state with the destination page.

The right-hand table of contents uses nested lists for heading levels h2 through h6. Each heading belongs to the nearest preceding shallower heading; skipped levels do not create empty groups. Source order, labels and anchors remain unchanged. Each nested group has its own indented dashed guide, using the existing RareUI curve and colors. The selected heading and its ancestor path receive separate group-owned indicators; a single line never spans unrelated heading depths. Neutral child guides keep the parent-child structure visible before a child is selected. Headings with children use the same native details/summary chevron as the left sidebar. The chevron toggles only that subtree; the heading link still navigates. Leaves have no chevron. Groups start expanded and user collapse is respected during scrolling. A collapsed active descendant keeps its parent path marked; scroll tracking uses the nearest visible ancestor for TOC visibility. Disclosure headings use the chevron as their path marker, while leaf rows retain curved guide endpoints. No hover or selection row boxes are added.

Indicator endpoints use the actual wrapped heading rows. Hover and keyboard previews stay within their sibling group. Reading state still exposes one aria-current location; ancestor indicators describe hierarchy without inventing additional selected locations. Resize and SPA changes recompute geometry and dispose old observers. Heading navigation, compact reading navigation, bilingual labels and theme colors remain compatible. Acceptance covers multiple parent groups, skipped levels, deep headings, wrapped rows, active ancestors, hover, resizing and SPA navigation on the default local instance.