1 +#
The System Rich Markdown Design 5 +Replace authored HTML specs, roadmaps, plans, issues, and research with human-editable rich Markdown document bundles.
7 +Preserve rich browser communication through one bundled renderer that can show either one document or the complete project dossier without mutating project files or requiring project tooling.
11 +- Core laws remain Markdown files at `.system/SYSTEM.md`, `.system/MISSION.md`, and `.system/RULES.md`.
12 +- Every authored governance document becomes a directory containing canonical `index.md` and document-owned assets.
13 +- The supported Markdown profile includes GFM, YAML frontmatter, footnotes, definition lists, GitHub alerts, Mermaid, TeX math, syntax highlighting, heading anchors, generated tables of contents, local assets, and raw HTML.
14 +- Accepted mockups remain free-form standalone HTML inside their owning spec bundle.
15 +- A bundled Node renderer and skill provide single-document and full-book browser views.
16 +- Single-document and book views use the exact same Markdown parser, article renderer, theme, and metadata renderer.
17 +- Rendered HTML is ephemeral and never becomes canonical project state.
18 +- HonKit is not used.
22 +Authored HTML communicates visually but makes routine human editing unpleasant.
24 +Markdown is easy to edit but becomes difficult to scan when diagrams, structured metadata, callouts, equations, or visual assets collapse into prose.
26 +AsciiDoc offers stronger native structure but imposes an unsuitable tooling and runtime burden.
28 +The System needs Markdown source ergonomics without surrendering deliberate browser presentation.
30 +##
Canonical Project Structure 39 +│ └── SYS-SPEC-001-rich-documents/
41 +│ ├── mockup-document-viewer.html
42 +│ ├── bundle-topology.svg
45 +│ └── SYS-ROADMAP-001-document-system/
48 +│ └── SYS-PLAN-001-renderer/
51 +│ └── SYS-ISSUE-001-rendering-gap/
54 + └── SYS-RESEARCH-001-renderers/
58 +Each typed directory contains only document bundles.
60 +A bundle name remains `<ID>-<slug>`.
62 +Every bundle contains exactly one canonical `index.md`.
64 +Every other file in the bundle is owned by that document.
66 +Simple documents remain visually simple because their bundle contains only `index.md`.
68 +Moving or deleting a document moves or deletes its complete asset boundary.
70 +##
Ownership And Mutation 72 +Existing core-law files remain human-owned and runtime-protected.
74 +A new spec bundle may be created directly after candidate validation.
76 +Every existing file inside a spec bundle is human-owned, including `index.md`, mockups, images, datasets, and other assets.
78 +Editing or replacing any existing spec-bundle file requires one interactive approval.
80 +Creating a missing asset inside an existing spec bundle does not require approval, matching the existing new-asset contract.
82 +Recognizable shell mutation of any spec-bundle path remains advisory-blocked because it bypasses candidate validation and interactive approval.
84 +Roadmaps and plans remain agent-authored with human review.
86 +Issues and research remain agent-authored.
88 +All authored `index.md` candidates receive shared metadata, reference, Markdown, and path validation regardless of ownership.
90 +##
Rich Markdown Profile 92 +The renderer supports one explicit source profile:
94 +- GitHub Flavored Markdown tables, task lists, autolinks, and strikethrough;
97 +- PHP Markdown-style definition lists;
98 +- GitHub blockquote alerts;
99 +- fenced Mermaid diagrams;
100 +- inline and display TeX math;
101 +- fenced-code syntax highlighting;
102 +- deterministic heading IDs and anchor links;
103 +- a compact collapsed `On this page` table of contents after the metadata ledger;
104 +- relative local images, media, downloadable files, and HTML assets;
105 +- normal remote references;
108 +The profile is owned by The System renderer rather than the project.
110 +Projects do not install packages, define scripts, or provide build configuration.
114 +Governed documents are trusted repository content.
116 +The renderer does not sanitize useful document syntax, block remote references, forbid cross-bundle links, or weaken Mermaid features under a false security boundary.
118 +Filesystem operations still resolve below the project root and temporary output root because path containment protects project data rather than policing document expression.
120 +Accepted mockups render in iframes to isolate their free-form layout and CSS from the document shell.
122 +Iframe isolation is a presentation boundary, not a claim that project-authored content is hostile.
124 +##
Frontmatter Rendering 126 +Frontmatter semantics belong to the broader System core model and require a separate design discussion.
128 +This design fixes the rendering contract without prematurely freezing that schema.
130 +The renderer parses every frontmatter field and preserves source order.
132 +The document mast shows a compact summary from available identity, type, state, and reference information.
134 +A collapsed metadata ledger renders every field, including unknown fields, nested maps, arrays, booleans, numbers, and nulls.
136 +Recognized document references become links when the graph can resolve them.
138 +No field disappears merely because the renderer does not understand its semantics.
140 +Single-document and book views render the same mast, summary, and complete ledger.
142 +##
Renderer Architecture 144 +The extension ships the renderer and all npm dependencies.
146 +The project supplies only `.system` source files.
148 +A unified/remark/rehype pipeline performs parsing and transformation.
150 +Representative package responsibilities are:
152 +- `remark-parse` and `remark-gfm` for Markdown and GFM;
153 +- `remark-frontmatter` or equivalent YAML extraction for metadata;
154 +- `remark-rehype` with dangerous HTML enabled followed by `rehype-raw` for authored raw HTML;
155 +- `remark-math` and `rehype-mathjax` for TeX;
156 +- `remark-definition-list` for definition lists;
157 +- `remark-github-blockquote-alert` for alerts;
158 +- `rehype-highlight` or a Shiki integration for code;
159 +- Mermaid's browser bundle for diagrams;
160 +- `minisearch` for generated full-text search.
162 +Exact dependency selection remains an implementation-plan decision, but one parser pipeline must own both viewing modes.
164 +The renderer has four internal stages:
166 +1. Discover and validate document bundles.
167 +2. Parse frontmatter and Markdown into one document model.
168 +3. Render reusable article HTML with Nugu styling.
169 +4. Wrap that article in either a single-document shell or the full-book shell.
171 +The article renderer is singular.
173 +No mode-specific Markdown parsing or metadata formatting is allowed.
175 +##
Single-Document View 177 +`/system-view [path-or-id]` delegates to a rendering skill.
179 +The skill resolves one bundle, invokes the bundled cross-platform renderer CLI, opens the temporary result in the browser, and exits.
181 +Authoring workflows offer the same view after writing or materially editing a document.
183 +Single-document output includes:
185 +- the complete document mast and frontmatter ledger;
186 +- the same collapsed in-document table of contents used by book pages;
187 +- rendered rich Markdown;
188 +- resolved local assets;
189 +- inline isolated previews for accepted mockups;
190 +- source-located diagnostics;
191 +- no book navigation or global search.
193 +No Pi tool is registered because viewing has no browser-to-agent event round-trip.
195 +A tool becomes justified only if a future design makes the rendered document editable or returns browser events to Pi.
199 +`/system-book` delegates to the same rendering skill and pipeline.
203 +- navigation grouped by project law, specs, roadmaps, plans, issues, and research;
204 +- stable previous and next document movement;
205 +- complete frontmatter rendering;
206 +- graph-derived references and backlinks;
207 +- generated full-text search across titles, IDs, frontmatter, and body content;
208 +- ranked results with document identity, type, and bounded context;
209 +- the same inline mockup previews and rich Markdown features as single-document view;
210 +- the same automatic light and dark Nugu theme.
212 +Search is generated from canonical source during ephemeral rendering.
214 +It is not limited to titles or navigation labels.
218 +Both viewing modes render every governed document and copy every governed bundle into temporary output while preserving relative paths.
220 +Single-document mode opens the selected page in its minimal shell but keeps the other generated pages available as cross-document link targets.
222 +Book mode opens the same generated page set through the navigation and search shell.
224 +Markdown links continue to resolve against their source document location.
226 +The renderer rewrites canonical Markdown document links to their existing rendered HTML targets while leaving ordinary asset and remote links intact.
228 +No project file is generated, renamed, edited, or deleted.
230 +Temporary output may be discarded after browser use.
232 +##
Mockup Integration 234 +Accepted mockups move from adjacent authored HTML filenames into their owning spec bundle.
239 +.system/specs/SYS-SPEC-001-rich-documents/
241 +└── mockup-document-viewer.html
244 +The spec links the mockup relatively:
247 +[Document viewer mockup](./mockup-document-viewer.html)
250 +The source remains a normal link.
252 +The renderer recognizes bundle-owned mockup HTML and upgrades that link into an isolated inline preview with an explicit full-size action.
254 +The generic `mockup` tool remains unchanged because its free-form HTML and interactive browser feedback are intentional.
258 +The renderer uses the shared Nugu palette with automatic light and dark modes.
260 +The book must remain calm rather than turning every semantic distinction into a color.
262 +Color usage follows these rules:
264 +- neutral surfaces carry hierarchy;
265 +- body text remains high contrast;
266 +- muted text identifies secondary metadata and navigation groups;
267 +- magenta is a sparse identity and active-state accent;
268 +- cyan identifies links and informational states;
269 +- warning and error colors appear only for corresponding diagnostics;
270 +- Mermaid, MathJax, syntax highlighting, alerts, navigation, and generated controls inherit the same theme tokens.
272 +The content surface uses the Nugu panel tone rather than a full black field in dark mode.
274 +Spacing, type weight, borders, and proximity do most grouping work.
276 +##
Diagnostics And Partial Rendering 278 +Renderer failures never mutate canonical source.
280 +A malformed extension reports its source path and location when available.
282 +The renderer preserves useful partial output instead of rejecting the complete document for one broken diagram, equation, link, or asset.
284 +Book mode reports document-specific failures without hiding healthy documents.
286 +Broken references and assets remain visible diagnostics.
288 +##
HonKit Experiment 290 +A temporary experiment tested HonKit 6.2.2 against eleven representative document bundles containing core laws, specs, a roadmap, plans, an issue, research, cross-document links, owned HTML mockups, SVG assets, frontmatter, tables, tasks, footnotes, definition lists, alerts, Mermaid, TeX, and code.
292 +Direct HonKit input failed because it requires `README.md`.
294 +An ephemeral staging copy with generated `README.md` and `SUMMARY.md` successfully preserved the proposed canonical bundle structure.
296 +It produced grouped navigation, previous and next links, search, valid cross-document links, and copied assets without changing source hashes.
298 +Its GitBook-legacy Markdown pipeline left Mermaid and TeX literal, rendered GitHub alerts as ordinary blockquotes, and failed to render definition lists.
300 +The built-in highlight plugin also reported Mermaid as an unknown language while still exiting successfully.
302 +HonKit-specific Mermaid and math plugins add a second plugin ecosystem with legacy GitBook assumptions and inconsistent dependency age.
304 +HonKit is actively maintained, but its parser architecture conflicts with the required rich Markdown contract.
306 +A second temporary prototype using unified rendered Mermaid, MathJax SVG, alerts, definition lists, footnotes, highlighted code, bundle assets, inline mockups, automatic Nugu theming, and full-text search while preserving source hashes.
308 +Therefore The System keeps HonKit's useful book interaction shape but does not use HonKit.
312 +This design replaces the authored-HTML document model before Phase 6 implements spec authoring.
314 +Phase 6 must be rewritten around rich Markdown bundles, rendering, and spec authoring rather than implementing HTML workflows that would immediately be deleted.
316 +The implementation must revise completed kernel and runtime assumptions where they currently require authored `.html` files.
318 +New project-local authored documents use bundle `index.md` paths only.
320 +Accepted mockups remain HTML assets and move inside spec bundles.
322 +Historical `docs/super/**` artifacts remain untouched unless a later explicit migration names them.
324 +The extension owns and versions the renderer theme as a bundled asset.
326 +Initialization stops creating `.system/system.css`, and the approved schema upgrade removes that obsolete machine-owned file.
330 +Automated checks must prove:
332 +- every authored type discovers bundle `index.md` files deterministically;
333 +- malformed bundle names, missing `index.md`, duplicate IDs, and invalid references produce diagnostics;
334 +- new spec files pass while every existing spec-bundle file requires approval before replacement;
335 +- single mode preserves working cross-document links without exposing book navigation;
336 +- single-document and book modes produce identical article HTML for the same source;
337 +- every frontmatter field renders in source order in both modes;
338 +- nested frontmatter values remain readable;
339 +- GFM, footnotes, definition lists, alerts, Mermaid, TeX, code highlighting, anchors, and raw HTML render;
340 +- local, cross-bundle, and remote references remain useful;
341 +- accepted mockups preview inline and open separately;
342 +- full-text search finds body and frontmatter terms absent from titles;
343 +- generated links and copied assets resolve;
344 +- light and dark themes meet contrast expectations and theme every generated component;
345 +- rendering leaves all project source hashes unchanged;
346 +- browser opening works on Windows, macOS, and Linux;
347 +- existing task branching and generic mockup behavior remain unchanged.
349 +Browser E2E covers Chromium and Firefox.
353 +- No in-browser document editing.
354 +- No persistent generated site.
355 +- No deployment or publishing workflow.
356 +- No project-owned renderer config, dependencies, or build tasks.
357 +- No AsciiDoc support.
358 +- No HonKit integration.
359 +- No automatic historical `docs/super/**` conversion.
360 +- No final frontmatter schema or lifecycle semantics in this design.
364 +- [Compact frontmatter summary and ledger](./2026-07-15-the-system-rich-markdown-design-mockup-compact-details-themed.html)