CLN WIKI

Self-Organising Documents

Structure generates navigation. Navigation makes structure visible. The document organises itself.

CLN Tools · Document Design · Vadim Shchetinkin

The document that knows its own shape.

Traditional documents require maintenance: you write content, then manually update a table of contents, then add navigation links, then keep them in sync as content changes. Every structural edit requires a matching metadata edit. The document and its navigation are two separate artefacts that drift apart over time.

CLN's numbered block structure breaks this pattern. When every section is // 01 ·, // 02 ·, and every block carries a ##id label, a renderer can automatically generate table of contents, sidebar navigation, progress tracking, and cross-reference maps — from the structure alone, with no separate metadata. The document describes itself.

CLN v2.0 = CONCEPT: Self-Organising Documents =documents whose navigation and metadata are derived automatically from their structural content #structure #navigation #rendering =key property: no manual TOC maintenance — structure IS the navigation // 01 · What CLN Structure Enables Automatically .Table of Contents =source: all // NN · Title block headers in document order =renderer scans headers → generates ordered list with jump links +always in sync — TOC regenerates on every render .Sidebar Navigation =source: // ##id Title block labels (v2.1 addressing) =renderer builds clickable nav panel with scroll-tracking +IntersectionObserver highlights current section as user scrolls .Progress Tracking =source: Slot 5 markers — ✔ done, ☐ pending, !! critical =renderer counts markers by type → generates completion summary +visual progress bar: N of M tasks complete .Cross-Reference Map =source: all »[text]##id cross-references =renderer builds directed graph: which sections reference which +backlinks: "this section is referenced from §02 and §05" .Risk / Gap Summary =source: all ! lines and ? lines without following → lines =renderer generates a "risks and open questions" panel at document top +executive summary generated from operator semantics — no prose required // 02 · The Authoring Contract =for a document to self-organise, the author follows a simple convention: .Rule 1 — Number your blocks =use // 01 ·, // 02 · — not freeform names .Rule 2 — Label blocks you want to reference =add ##id to block headers that need addressability .Rule 3 — Use markers consistently =✔ only when truly done, ☐ only for real pending items =consistency makes auto-progress meaningful, not misleading .Rule 4 — Close your questions =if you open a ? question, either answer it (→) or leave it open intentionally =gaps are surfaced — unanswered questions become visible debt // 03 · Real Implementations .super-demo.html =9-chapter CLN showcase with fixed sidebar, chapter tabs, progress dots =IntersectionObserver syncs 3 navigation systems simultaneously =all navigation generated from CLN block structure — no manual HTML .step-test-auto.html =CLN-driven step-by-step test guide with auto-progress =✔ / ☐ markers drive a completion percentage bar .vscode-deploy-guide.html =deploy guide generated from .cln source — auto sidebar from block headers =demonstrates CLN → HTML render pipeline in production // 04 · Why This Matters for Knowledge Management .The Maintenance Trap =most PKM systems fail because maintenance cost exceeds capture value =manually updating TOCs, indices, and cross-references is friction =friction causes abandonment — the second-brain problem .The CLN Solution =authoring follows a consistent pattern → no extra maintenance step =renderer handles navigation → author never touches HTML or TOC manually +write more, maintain less — friction reduced to near zero →a PKM system you actually keep using @related: CLN Addressing v2.1, PKM, Second Brain, Atomic Notes

The structure is the product.

The conventional view of document structure treats it as overhead — something you add on top of content to help readers navigate. Self-organising CLN documents invert this: the structure is the content, in the sense that it carries meaning (operator semantics), enables navigation (block headers and anchors), and generates metadata (progress, gaps, connections) automatically.

This is not a rendering trick. It is a consequence of semantic authoring: when every line carries a type, and every block carries an identity, the document already contains everything a navigation system needs. The renderer merely makes it visible.

A well-structured CLN document is already a dashboard. The renderer just turns it on.
← CLN Addressing PKM →