CLN Wiki · Specification
Addressing v2.1
= ##id · // ##id · »[text]##id → internal links in plain text ~ 6 sections
01// Line Anchors ##id Syntax
// ##anch-def · Definition =Line anchor — a named address placed at the end of any CLN line##anch-def =format: ##identifier — double hash + alphanumeric + hyphens =position: end of line, after content and tags =scope: document-unique — no two lines share the same id // ##anch-examples · Examples .= Redis is the primary cache ##redis .! Memory limit 4GB — hard ceiling ##mem-limit .→ Ship v2.1 in Sprint 3 ##decision-ship .? Latency budget unresolved ##q-latency // ##anch-why · Why anchors at line level +granular — link to exact claim, not just section +stable — id survives text edits if author keeps the tag +readable in plain text — ##redis is self-explanatory without rendering -manual — author must assign ids; no auto-generation
02// Block Labels // ##id Syntax
// ##block-def · Definition =Block label — a comment line that names and addresses an entire block##block-def =format: // ##id Title Text =the ##id comes immediately after // =title text is human-readable; id is machine-addressable // ##block-examples · Examples .// ##arch Architecture Overview .// ##risks · Known Risks .// ##verdict 04 · Final Decision .// ##q-open Open Questions // ##block-why · Block label vs line anchor =line anchor ##id — points to one specific line =block label // ##id Title — addresses a whole semantic section →use line anchor when the claim itself matters — link to §03 → →use block label when the context matters — "see the Architecture section"
03// Cross-References »[text]##id Syntax
// ##xref-def · Definition =Cross-reference — inline link from one line to a named anchor elsewhere##xref-def =format: »[display text]##target-id =» is the guillemet right-double-angle — U+00BB =display text = what reader sees; target-id = where to jump // ##xref-examples · Examples in context .= See »[Architecture]##arch for full context .! This risk depends on »[Memory Limit]##mem-limit .→ Resolved via »[Sprint 3 decision]##decision-ship .~ Blocks »[latency]##q-latency vs »[throughput]##q-thru // ##xref-plain · Why » works in plain text +»[text] is visually distinct — guillemet signals "this is a reference" +readable without rendering — intent is clear even as raw characters +greppable — grep '»\[' finds all cross-references in a document +renderable — parser converts to <a href="#target-id"> trivially
04// Line Anatomy Reference
// ##anat-slots · Five slots in every CLN line =slot order: OPERATOR · CONTENT · #tags · ##anchor · STATUS##five-slots =only OPERATOR is required — all others optional =order is fixed — anchor always comes after tags, status always last
! operator
·
DB connection fails under load content text
·
#infra tag
·
##db-risk anchor
·
!! critical status
= operator
·
Redis cache — 4GB hard limit content text
·
#cache tag
·
##redis anchor
·
— optional
// ##anat-rules · Hard rules !anchor must be unique per document — duplicate ids break cross-references !anchor must follow tags — #tag ##id is correct; ##id #tag is not !no spaces in id — use hyphens: ##db-risk not ##db risk
05// vs Markdown Anchors Comparison
Markdown -anchors only on headings — ## Section → #section -no line-level granularity -id derived from heading text — breaks on rename -not greppable in plain text +auto-generated — no manual work +universal — every Markdown renderer supports it
CLN v2.1 +any line can be anchored — not just headings +explicit id — survives text changes +##id readable and greppable as plain text +cross-refs visible as »[text]##id without rendering -manual — author assigns every id -requires CLN-aware renderer for HTML links
FeatureMarkdownCLN v2.1
Anchor scope Headings only Any line
Id stability Breaks on heading rename Explicit — rename-safe
Plain text read [text](#id) — partial »[text]##id — fully readable
Block labels No equivalent // ##id Title
Grep-ability Poor grep '##' finds all anchors
06// Live Demo Example
// ##demo-desc · A real document fragment with full addressing .the document below uses all three addressing features together .left panel — raw CLN plain text  |  right panel — rendered result
Project Alpha · Architecture Decision addressing demo
Raw CLN
// ##arch Architecture Overview = Redis is the primary cache #infra ##redis = Postgres for persistent storage #infra ##postgres . All services behind API gateway ##gateway // ##risks · Known Risks ! Redis eviction under peak load #infra ##redis-risk depends on »[cache config]##redis ! Gateway single point of failure ##gw-risk !! critical see »[gateway spec]##gateway // ##verdict · Decision → Accept »[redis risk]##redis-risk — add replica → Resolve »[gw risk]##gw-risk before launch ✔
Rendered // ##arch · Architecture Overview =Redis is the primary cache #infra##redis =Postgres for persistent storage #infra##postgres .All services behind API gateway##gateway // ##risks · Known Risks !Redis eviction under peak load #infra##redis-risk .depends on »[cache config]##redis !Gateway single point of failure##gw-risk .see »[gateway spec]##gateway // ##verdict · Decision →Accept »[redis risk]##redis-risk — add replica →Resolve »[gw risk]##gw-risk before launch ✔
// ##demo-takeaway · What the demo shows →block label // ##risks addresses the whole risk section →line anchor ##redis-risk addresses one specific claim →cross-ref »[redis risk]##redis-risk links verdict back to the exact risk line →all three readable as plain text — the document works without a renderer @→ Full Specification v2.1 — complete syntax reference @→ CLN Overview — operators + system introduction