@entropicwarrior/sdoc 0.2.11 → 0.2.12

package/docs/reference/sdoc-authoring.sdoc

@@ -365,6 +365,39 @@ Content of Section B.
             Do not write \`@setup\` when the target scope is in a different file — it will be flagged as a broken reference.
         }
 
+        # Citations @citations
+        {
+            Use \`[@key]\` in text to cite a source. Define citations in a \`{[citations]\` block. The renderer assigns numbers by order of first appearance and links everything together.
+
+            ```
+            # Findings {
+                Edge AI is growing rapidly [@mm-edge-ai]. The chip market
+                is expected to double by 2031 [@mordor-chips].
+
+                {[citations]
+                    - @mm-edge-ai MarketsandMarkets, "Edge AI Hardware
+                      Market," Report SE 7017, June 2025.
+                    - @mordor-chips Mordor Intelligence, "Edge AI Chips
+                      Market Size & Share Analysis," 2026.
+                }
+            }
+            ```
+
+            {[.]
+                - \`[@key]\` renders as a clickable superscript number (e.g. \`[1]\`) linking to the citation entry
+                - \`[@key1, @key2]\` renders as \`[1, 3]\` with each number individually linked
+                - The same \`[@key]\` used multiple times always renders the same number
+                - Keys follow \`@slug\` conventions: lowercase kebab-case
+                - Citation text is free-form SDOC inline content — links, bold, italics all work
+                - Each citation entry includes a back-link (\`\u21A9\`) to the first place it was cited
+                - Numbering is by order of first \`[@key]\` appearance, not by definition order
+                - Multiple \`{[citations]\` blocks are allowed — numbering is unified across all blocks
+                - A \`[@key]\` with no matching definition is flagged as a broken citation
+                - A defined citation that is never referenced produces a warning
+                - Citation keys are document-local, like \`@slug\` references
+            }
+        }
+
         # Code Blocks @code-blocks
         {
             Fenced with triple backticks. Content inside is raw (no parsing):
@@ -766,5 +799,19 @@ Content of Section B.
 
             **Also right:** \`[See domain-model.sdoc § my-section](./domain-model.sdoc#my-section)\`
         }
+
+        # [@key] vs @key @citation-vs-ref
+        {
+            \`[@key]\` is a **citation reference** — it renders as a numbered superscript linking to a citation entry. \`@key\` is a **section reference** — it renders as a clickable link to a heading with that ID.
+
+            Confusing them will produce errors:
+
+            {[.]
+                - Writing \`@smith2020\` when you mean \`[@smith2020]\` creates a broken section reference (there is no heading with ID \`smith2020\`)
+                - Writing \`[@setup]\` when you mean \`@setup\` creates a broken citation (there is no citation definition for \`setup\`)
+            }
+
+            Rule of thumb: square brackets mean citation, bare \`@\` means section.
+        }
     }
 }

package/lexica/specification.sdoc

@@ -474,6 +474,84 @@ Content of Section B.
             }
         }
 
+        # Citations @citations
+        {
+            Citations provide stable, auto-numbered source references. An inline citation reference uses `[@key]`; citation definitions go in a `{[citations]` block.
+
+            # Inline Citation References @citation-refs
+            {
+                ```
+                The market is growing rapidly [@mm-report].
+                Multiple sources agree [@mm-report, @mordor-analysis].
+                ```
+
+                {[.]
+                    - `[@key]` inserts a citation reference that renders as a clickable superscript number (e.g. `[1]`) linking to the corresponding entry in the `{[citations]` block
+                    - `[@key1, @key2]` renders as `[1, 3]` (or whatever the assigned numbers are), with each number individually linked
+                    - Whitespace around commas is optional and ignored
+                    - Keys follow the existing `@slug` convention: lowercase kebab-case
+                    - `[@key]` is visually and semantically distinct from `@slug` — the former is a citation, the latter is a section reference
+                    - The same `[@key]` used multiple times always renders the same number
+                    - Citation keys are document-local, like section references
+                }
+            }
+
+            # Citation Definition Block @citation-block
+            {
+                ```
+{[citations]
+    - @mm-report MarketsandMarkets, "Edge AI Hardware Market,"
+      Report SE 7017, June 2025.
+    - @mordor-analysis Mordor Intelligence, "Edge AI Chips Market
+      Size & Share Analysis," 2026.
+}
+                ```
+
+                {[.]
+                    - `{[citations]` opens a citation definition block (no closing brace on the same line)
+                    - Each citation is a list item with a `- @key` prefix followed by free-form inline content
+                    - Citation text supports full SDOC inline formatting: links, bold, italics, inline code
+                    - There are no structured bibliographic fields — the author formats the citation however they want
+                    - Item text can span multiple continuation lines (same rules as list item continuation)
+                    - The closing `}` must be on its own line
+                    - Works with K&R brace style: `# References {[citations]`
+                }
+            }
+
+            # Numbering @citation-numbering
+            {
+                {[.]
+                    - Numbers are assigned by order of first appearance of `[@key]` in the document text, starting at 1
+                    - The `{[citations]` block renders entries sorted by assigned number, regardless of definition order
+                    - Numbers always increase monotonically as the reader moves through the document
+                    - Defined but unreferenced citations are appended after all referenced entries
+                }
+            }
+
+            # Multiple Blocks @citation-multiple-blocks
+            {
+                Multiple `{[citations]` blocks are allowed in a single document. All blocks share a unified numbering sequence. Each block renders at its own position in the document. This lets authors place citation definitions near the content that references them.
+            }
+
+            # Rendering @citation-rendering
+            {
+                {[.]
+                    - In-text: `[@key]` renders as a superscript bracketed number linking to the entry (e.g. `[1]`)
+                    - Citation list: each entry renders with its assigned number, the citation text, and a back-link (`\u21A9`) to the first location where it was cited
+                    - Only the first occurrence of each `[@key]` in the text receives an anchor ID for the back-link
+                }
+            }
+
+            # Errors and Warnings @citation-errors
+            {
+                {[.]
+                    - `[@key]` with no matching definition in any `{[citations]` block: **warning** (renders with a broken-reference indicator, same as a broken `@slug`)
+                    - Citation defined but never referenced: **warning** (entry is still rendered, but the author is told it is unused)
+                    - Invalid entry inside `{[citations]` (not matching `- @key text`): **parse error**
+                }
+            }
+        }
+
         # Links @links
         {
             Markdown-style links with absolute URLs or relative file paths:
@@ -578,9 +656,13 @@ Content of Section B.
                 - Warning marker: `{!text!}` (orange highlight)
                 - Negative marker: `{-text-}` (red highlight)
                 - Highlight: `{~text~}` (yellow highlight)
+                - Citation reference: `[@key]` (numbered superscript link to citation entry)
+                - Multiple citation references: `[@key1, @key2]` (each individually linked)
             }
 
             Inline math requires non-whitespace immediately after the opening `$` and before the closing `$`. A plain `$` followed by a digit (e.g. `$100`) does not trigger math mode because there is no closing `$`.
+
+            Citation references (`[@key]`) are parsed before link syntax. `[@key]` is always a citation reference even if followed by `(url)`. Use `\[@key]` for a literal `[@key]` in text.
         }
 
         # Escaping @escaping
@@ -949,6 +1031,7 @@ Content of Section A.
             - `}` scope close
             - `{[.]` / `{[#]` list open
             - `{[table]` / `{[table <flags>]` table open
+            - `{[citations]` citations block open
             - `>` blockquote line
             - `---` / `***` / `___` horizontal rule
             - `` ``` `` code fence
@@ -977,18 +1060,19 @@ Content of Section A.
                           ((ws id)? (ws scope_type)? | (ws scope_type)? (ws id)?) ws block_opener ;
         id            = "@" ident ;
         scope_type    = ":" ident ;   (* id and scope_type may appear in either order *)
-        block_opener  = "{" | "{[.]" | "{[#]" | table_open ;
+        block_opener  = "{" | "{[.]" | "{[#]" | table_open | citations_open ;
         block         = "{" ws? block_body "}" ;
         braceless_body = { paragraph | code_block | data_block | blockquote
                          | implicit_list | horizontal_rule | headingless_scope
-                         | list_scope | table_scope | bare_directive
-                         | line_comment | blank } ;
+                         | list_scope | table_scope | citations_scope
+                         | bare_directive | line_comment | blank } ;
 
         bare_directive = "@" ("meta" | "about") (ws block | braceless_body) ;
         block_body    = { blank | line_comment | paragraph | scope
                         | headingless_scope | list_scope | table_scope
-                        | implicit_list | blockquote | horizontal_rule
-                        | code_block | data_block | bare_directive | comma_sep } ;
+                        | citations_scope | implicit_list | blockquote
+                        | horizontal_rule | code_block | data_block
+                        | bare_directive | comma_sep } ;
         headingless_scope = "{" ws? block_body "}" ;
         list_scope    = list_open ws? list_body "}" ;
         list_open     = "{[.]" | "{[#]" ;
@@ -1001,6 +1085,10 @@ Content of Section A.
         pixels        = digit { digit } "px" ;
         table_body    = table_row { table_row } ;
         table_row     = cell { "|" cell } ;
+        citations_scope = citations_open ws? citations_body "}" ;
+        citations_open  = "{[citations]" ;
+        citations_body  = { blank | citation_entry } ;
+        citation_entry  = "-" ws "@" ident ws text_line { continuation_line } ;
         list_body     = { blank | comma_sep | scope | list_item_shorthand
                         | anonymous_item } ;
         implicit_list = list_item_shorthand { list_item_shorthand } ;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC - Docs for Human/Agent Teams",
   "description": "A plain-text documentation format with explicit brace scoping — deterministic parsing, AI-agent efficiency, and 10-50x token savings vs Markdown.",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "publisher": "entropicwarrior-msenfin",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -11,6 +11,7 @@ const COMMAND_SCOPE_CLOSE = "}";
 const COMMAND_LIST_BULLET = "{[.]";
 const COMMAND_LIST_NUMBER = "{[#]";
 const COMMAND_TABLE = "{[table]";
+const COMMAND_CITATIONS = "{[citations]";
 const COMMAND_CODE_FENCE = "```";
 
 const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-", "^", "?", "|"]);
@@ -41,6 +42,10 @@ function isTableCommand(text) {
   return /^\{\[table(?:\s+[^\]]*?)?\]$/.test(text);
 }
 
+function isCitationsCommand(text) {
+  return text === COMMAND_CITATIONS;
+}
+
 function parseTableOptions(text) {
   const match = text.match(/^\{\[table(?:\s+(.*))?\]$/);
   if (!match) return {};
@@ -299,6 +304,12 @@ function parseBlock(cursor, kind) {
       continue;
     }
 
+    if (isCitationsCommand(trimmed)) {
+      flushParagraph();
+      nodes.push(parseCitationsBlock(cursor));
+      continue;
+    }
+
     if (trimmed === COMMAND_SCOPE_OPEN) {
       flushParagraph();
       const scopeStartLine = cursor.index + 1;
@@ -340,6 +351,13 @@ function extractTrailingOpener(text) {
       return { text: trimmed.slice(0, pos).trimEnd(), opener: tableMatch[0] };
     }
   }
+  // Check for citations command: {[citations]
+  if (trimmed.endsWith(COMMAND_CITATIONS)) {
+    const pos = trimmed.length - COMMAND_CITATIONS.length;
+    if (!(pos > 0 && trimmed[pos - 1] === "\\")) {
+      return { text: trimmed.slice(0, pos).trimEnd(), opener: COMMAND_CITATIONS };
+    }
+  }
   // Check other openers
   const openers = [COMMAND_LIST_NUMBER, COMMAND_LIST_BULLET, COMMAND_SCOPE_OPEN];
   for (const opener of openers) {
@@ -388,6 +406,8 @@ function parseScope(cursor) {
     } else if (isTableCommand(trailing.opener)) {
       const tableOpts = parseTableOptions(trailing.opener);
       children = [parseTableBody(cursor, scopeStartLine, tableOpts)];
+    } else if (isCitationsCommand(trailing.opener)) {
+      children = [parseCitationsBody(cursor, scopeStartLine)];
     } else {
       children = parseBlock(cursor, "normal");
     }
@@ -545,6 +565,12 @@ function parseBracelessBlock(cursor) {
       continue;
     }
 
+    if (isCitationsCommand(trimmed)) {
+      flushParagraph();
+      nodes.push(parseCitationsBlock(cursor));
+      continue;
+    }
+
     if (!paragraphLines.length) {
       paragraphStartLine = cursor.index + 1;
     }
@@ -594,6 +620,10 @@ function parseScopeBlock(cursor) {
       return { blockType: "normal", children: [parseTableBlock(cursor)] };
     }
 
+    if (isCitationsCommand(trimmed)) {
+      return { blockType: "normal", children: [parseCitationsBlock(cursor)] };
+    }
+
     // No block opener found — braceless scope
     return { blockType: "braceless" };
   }
@@ -689,6 +719,7 @@ function isListContinuationLine(trimmedLeft) {
   if (trimmed === COMMAND_LIST_BULLET) return false;
   if (trimmed === COMMAND_LIST_NUMBER) return false;
   if (isTableCommand(trimmed)) return false;
+  if (isCitationsCommand(trimmed)) return false;
   if (trimmed === ",") return false;
   if (isHeadingLine(trimmedLeft)) return false;
   if (isBlockquoteLine(trimmedLeft)) return false;
@@ -720,6 +751,8 @@ function parseListItemLine(cursor, info, allowContinuation = false) {
     } else if (isTableCommand(trailing.opener)) {
       const tableOpts = parseTableOptions(trailing.opener);
       children = [parseTableBody(cursor, itemStartLine, tableOpts)];
+    } else if (isCitationsCommand(trailing.opener)) {
+      children = [parseCitationsBody(cursor, itemStartLine)];
     } else {
       children = parseBlock(cursor, "normal");
     }
@@ -817,6 +850,63 @@ function parseTableBody(cursor, tableStartLine, options) {
   return tableNode;
 }
 
+function parseCitationsBlock(cursor) {
+  const startLine = cursor.index + 1;
+  cursor.next();
+  return parseCitationsBody(cursor, startLine);
+}
+
+function parseCitationsBody(cursor, startLine) {
+  const entries = [];
+
+  while (!cursor.eof()) {
+    const line = cursor.current();
+    const trimmedLeft = line.replace(/^\s+/, "");
+    const trimmed = trimmedLeft.trim();
+
+    if (trimmed === "") {
+      cursor.next();
+      continue;
+    }
+
+    if (trimmed === COMMAND_SCOPE_CLOSE) {
+      cursor.next();
+      break;
+    }
+
+    // Citation items: - @key free-form text
+    const citationMatch = trimmed.match(/^-\s+@([A-Za-z_][A-Za-z0-9_-]*)\s+([\s\S]*)$/);
+    if (citationMatch) {
+      const entryStartLine = cursor.index + 1;
+      const key = citationMatch[1];
+      let text = citationMatch[2].trim();
+      cursor.next();
+
+      // Collect continuation lines (indented text not starting with - @key or })
+      while (!cursor.eof()) {
+        const nextLine = cursor.current();
+        const nextTrimmedLeft = nextLine.replace(/^\s+/, "");
+        const nextTrimmed = nextTrimmedLeft.trim();
+
+        if (nextTrimmed === "") break;
+        if (nextTrimmed === COMMAND_SCOPE_CLOSE) break;
+        if (/^-\s+@[A-Za-z_]/.test(nextTrimmed)) break;
+
+        text += " " + nextTrimmed;
+        cursor.next();
+      }
+
+      entries.push({ key, text, lineStart: entryStartLine, lineEnd: cursor.index });
+      continue;
+    }
+
+    cursor.error("Invalid citation entry (expected '- @key text').");
+    cursor.next();
+  }
+
+  return { type: "citations", entries, lineStart: startLine, lineEnd: cursor.index };
+}
+
 function parseOptionalBlock(cursor) {
   while (!cursor.eof()) {
     const line = cursor.current();
@@ -1123,6 +1213,18 @@ function parseImageWidth(raw) {
   return { src: raw };
 }
 
+function parseCitationKeys(inner) {
+  // Parse "@key1, @key2, ..." — returns array of keys or null if invalid
+  const parts = inner.split(",");
+  const keys = [];
+  for (const part of parts) {
+    const match = part.trim().match(/^@([A-Za-z_][A-Za-z0-9_-]*)$/);
+    if (!match) return null;
+    keys.push(match[1]);
+  }
+  return keys.length > 0 ? keys : null;
+}
+
 function parseInline(text) {
   const nodes = [];
   let buffer = "";
@@ -1252,6 +1354,21 @@ function parseInline(text) {
       }
     }
 
+    // Citation references: [@key] or [@key1, @key2]
+    if (ch === "[" && text[i + 1] === "@") {
+      const endBracket = findUnescaped(text, i + 1, "]");
+      if (endBracket !== -1) {
+        const inner = text.slice(i + 1, endBracket).trim();
+        const keys = parseCitationKeys(inner);
+        if (keys) {
+          flush();
+          nodes.push({ type: "citation_ref", keys });
+          i = endBracket + 1;
+          continue;
+        }
+      }
+    }
+
     if (ch === "[") {
       const endLabel = findUnescaped(text, i + 1, "]");
       if (endLabel !== -1 && text[endLabel + 1] === "(") {
@@ -1371,6 +1488,81 @@ function findUnescaped(text, start, token) {
 
 let _renderOptions = {};
 
+// --- Citation numbering ---
+// Built before rendering; maps citation key → { number, anchorId }
+// anchorId is the id of the first inline citation_ref for back-linking
+let _citationNumbering = new Map();
+let _citationDefinitions = new Map(); // key → { text, lineStart, lineEnd }
+
+function buildCitationNumbering(nodes) {
+  const numbering = new Map();
+  const definitions = new Map();
+  let counter = 0;
+
+  // First pass: collect all citation_ref keys in document order to assign numbers
+  function walkInlineNodes(inlineNodes) {
+    for (const node of inlineNodes) {
+      if (node.type === "citation_ref") {
+        for (const key of node.keys) {
+          if (!numbering.has(key)) {
+            counter += 1;
+            numbering.set(key, { number: counter, anchorId: `citeref-${key}` });
+          }
+        }
+      }
+      if (node.children) walkInlineNodes(node.children);
+    }
+  }
+
+  function walkInlineText(text) {
+    walkInlineNodes(parseInline(text));
+  }
+
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "paragraph" && node.text) {
+        walkInlineText(node.text);
+      } else if (node.type === "blockquote" && node.paragraphs) {
+        for (const para of node.paragraphs) {
+          walkInlineText(para);
+        }
+      } else if (node.type === "scope") {
+        if (node.title) walkInlineText(node.title);
+        if (node.children) walk(node.children);
+      } else if (node.type === "list" && node.items) {
+        walk(node.items);
+      } else if (node.type === "table") {
+        if (node.headers) {
+          for (const cell of node.headers) walkInlineText(cell);
+        }
+        if (node.rows) {
+          for (const row of node.rows) {
+            for (const cell of row) walkInlineText(cell);
+          }
+        }
+      } else if (node.type === "citations") {
+        // Collect definitions
+        for (const entry of node.entries) {
+          if (!definitions.has(entry.key)) {
+            definitions.set(entry.key, { text: entry.text, lineStart: entry.lineStart, lineEnd: entry.lineEnd });
+          }
+        }
+      }
+    }
+  }
+  walk(nodes);
+
+  // Assign numbers to defined-but-unreferenced citations (appended after referenced ones)
+  for (const [key, def] of definitions) {
+    if (!numbering.has(key)) {
+      counter += 1;
+      numbering.set(key, { number: counter, anchorId: null });
+    }
+  }
+
+  return { numbering, definitions };
+}
+
 function dataLineAttrs(node) {
   if (node.lineStart == null) {
     return "";
@@ -1441,6 +1633,24 @@ function renderInlineNodes(nodes) {
           }
           return `<a class="sdoc-ref" href="${href}">@${escapeHtml(node.id)}</a>`;
         }
+        case "citation_ref": {
+          if (!_renderOptions._citationRefSeen) _renderOptions._citationRefSeen = new Set();
+          const parts = node.keys.map((key) => {
+            const info = _citationNumbering.get(key);
+            const isBroken = !_citationDefinitions.has(key);
+            if (isBroken) {
+              // Undefined citation — render with warning
+              const num = info ? info.number : escapeHtml(key);
+              return `<a class="sdoc-citation-ref sdoc-broken-ref" href="#cite-${escapeAttr(key)}"><span class="sdoc-broken-icon">\u26A0</span>${num}</a>`;
+            }
+            // Only the first occurrence of each key gets the back-link anchor id
+            const isFirst = !_renderOptions._citationRefSeen.has(key);
+            if (isFirst) _renderOptions._citationRefSeen.add(key);
+            const idAttr = isFirst ? ` id="citeref-${escapeAttr(key)}"` : "";
+            return `<a class="sdoc-citation-ref"${idAttr} href="#cite-${escapeAttr(key)}">${info.number}</a>`;
+          });
+          return `<sup class="sdoc-citation-group">[${parts.join(", ")}]</sup>`;
+        }
         case "code":
           return `<code class="sdoc-inline-code">${escapeHtml(node.value)}</code>`;
         case "em":
@@ -1517,6 +1727,33 @@ function renderScope(scope, depth, isTitleScope = false) {
   return `<section class="sdoc-scope${rootClass}${typeClass}"${typeAttr}>${heading}${childrenHtml}</section>`;
 }
 
+function renderCitations(node) {
+  const dl = dataLineAttrs(node);
+
+  // Build entries sorted by assigned citation number
+  const sorted = [];
+  for (const entry of node.entries) {
+    const info = _citationNumbering.get(entry.key);
+    if (info) {
+      sorted.push({ key: entry.key, text: entry.text, number: info.number, anchorId: info.anchorId });
+    } else {
+      // Defined but no number (shouldn't happen if buildCitationNumbering ran, but be safe)
+      sorted.push({ key: entry.key, text: entry.text, number: Infinity, anchorId: null });
+    }
+  }
+  sorted.sort((a, b) => a.number - b.number);
+
+  const items = sorted.map((entry) => {
+    const backLink = entry.anchorId
+      ? ` <a class="sdoc-citation-backlink" href="#${escapeAttr(entry.anchorId)}" title="Back to text">\u21A9</a>`
+      : "";
+    const unreferenced = entry.anchorId === null ? " sdoc-citation-unreferenced" : "";
+    return `<li id="cite-${escapeAttr(entry.key)}" class="sdoc-citation-entry${unreferenced}" value="${entry.number}"><span class="sdoc-citation-text">${renderInline(entry.text)}</span>${backLink}</li>`;
+  }).join("\n");
+
+  return `<ol class="sdoc-citations"${dl}>${items}</ol>`;
+}
+
 function renderList(list, depth) {
   return renderListFromItems(list.listType, list.items, depth, list);
 }
@@ -1955,6 +2192,8 @@ function renderNode(node, depth) {
       const editable = _renderOptions.editable ? ` contenteditable="true"` : "";
       return `<p class="sdoc-paragraph"${dl}${editable}>${renderInline(node.text)}</p>`;
     }
+    case "citations":
+      return renderCitations(node);
     case "code": {
       if (node.lang === "mermaid") {
         return `<pre class="mermaid"${dl}>${escapeHtml(node.text)}</pre>`;
@@ -2392,6 +2631,62 @@ const DEFAULT_STYLE = `
     margin-right: 0.15em;
   }
 
+  .sdoc-citation-group {
+    font-size: 0.8em;
+    line-height: 1;
+    vertical-align: super;
+  }
+
+  .sdoc-citation-ref {
+    color: var(--sdoc-accent);
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  .sdoc-citation-ref:hover {
+    text-decoration: underline;
+  }
+
+  .sdoc-citations {
+    margin: 1.5rem 0;
+    padding: 1rem 0 0.5rem 0;
+    border-top: 1px solid var(--sdoc-border);
+    list-style: none;
+    counter-reset: none;
+  }
+
+  .sdoc-citation-entry {
+    margin: 0.4rem 0;
+    padding-left: 2.5rem;
+    position: relative;
+    line-height: 1.6;
+    font-size: 0.92em;
+  }
+
+  .sdoc-citation-entry::before {
+    content: "[" attr(value) "]";
+    position: absolute;
+    left: 0;
+    color: var(--sdoc-muted);
+    font-weight: 600;
+    font-size: 0.9em;
+  }
+
+  .sdoc-citation-unreferenced {
+    opacity: 0.6;
+  }
+
+  .sdoc-citation-backlink {
+    color: var(--sdoc-accent);
+    text-decoration: none;
+    margin-left: 0.3em;
+    font-size: 0.85em;
+  }
+
+  .sdoc-citation-backlink:hover {
+    text-decoration: underline;
+  }
+
   .sdoc-image {
     display: inline-block;
     max-width: 100%;
@@ -2592,7 +2887,7 @@ hljs.COMMENT('^\\\\s*//','$'),
   {className:'link',begin:'\\\\(',end:'\\\\)'}
 ]},
 {className:'keyword',begin:'\\\\{[!?+\\\\-=~^]',end:'[!?+\\\\-=~^]\\\\}'},
-{className:'keyword',begin:'\\\\{\\\\[(?:\\\\.|#|\\\\d+|table)\\\\]'},
+{className:'keyword',begin:'\\\\{\\\\[(?:\\\\.|#|\\\\d+|table|citations)\\\\]'},
 {className:'strong',begin:'\\\\*\\\\*',end:'\\\\*\\\\*'},
 {className:'emphasis',begin:'(?<!\\\\*)\\\\*(?!\\\\*)',end:'\\\\*(?!\\\\*)'},
 {className:'deletion',begin:'~~',end:'~~'},
@@ -2648,12 +2943,26 @@ function renderBodyNodes(nodes) {
 function renderHtmlBody(text) {
   const parsed = parseSdoc(text);
   const metaResult = extractMeta(parsed.nodes);
-  return renderBodyNodes(metaResult.nodes);
+  const savedOptions = _renderOptions;
+  _renderOptions = {};
+  const citationData = buildCitationNumbering(metaResult.nodes);
+  _citationNumbering = citationData.numbering;
+  _citationDefinitions = citationData.definitions;
+  const result = renderBodyNodes(metaResult.nodes);
+  _citationNumbering = new Map();
+  _citationDefinitions = new Map();
+  _renderOptions = savedOptions;
+  return result;
 }
 
 function renderHtmlDocumentFromParsed(parsed, title, options = {}) {
   _renderOptions = options.renderOptions ?? {};
+  const citationData = buildCitationNumbering(parsed.nodes);
+  _citationNumbering = citationData.numbering;
+  _citationDefinitions = citationData.definitions;
   const body = renderBodyNodes(parsed.nodes);
+  _citationNumbering = new Map();
+  _citationDefinitions = new Map();
   _renderOptions = {};
   const errorHtml = renderErrors(parsed.errors);
 
@@ -2782,11 +3091,12 @@ function formatSdoc(text, indentStr = "    ") {
       continue;
     }
 
-    // Standalone opener: {, {[.], {[#], {[table]
+    // Standalone opener: {, {[.], {[#], {[table], {[citations]
     if (trimmed === COMMAND_SCOPE_OPEN ||
         trimmed === COMMAND_LIST_BULLET ||
         trimmed === COMMAND_LIST_NUMBER ||
-        isTableCommand(trimmed)) {
+        isTableCommand(trimmed) ||
+        isCitationsCommand(trimmed)) {
       result.push(indentStr.repeat(depth) + trimmed);
       depth++;
       continue;
@@ -3017,6 +3327,7 @@ function collectAllIds(nodes) {
 function collectInlineRefs(nodes) {
   const refs = [];
   const links = [];
+  const citationRefs = [];
 
   function walkInlineNodes(inlineNodes, lineStart, lineEnd) {
     for (const node of inlineNodes) {
@@ -3024,6 +3335,10 @@ function collectInlineRefs(nodes) {
         refs.push({ id: node.id, lineStart, lineEnd });
       } else if (node.type === "link") {
         links.push({ href: node.href, lineStart, lineEnd });
+      } else if (node.type === "citation_ref") {
+        for (const key of node.keys) {
+          citationRefs.push({ key, lineStart, lineEnd });
+        }
       }
       if (node.children) {
         walkInlineNodes(node.children, lineStart, lineEnd);
@@ -3073,7 +3388,24 @@ function collectInlineRefs(nodes) {
     }
   }
   walk(nodes);
-  return { refs, links };
+  return { refs, links, citationRefs };
+}
+
+function collectCitationDefinitions(nodes) {
+  const defs = [];
+  function walk(nodeList) {
+    for (const node of nodeList) {
+      if (node.type === "citations") {
+        for (const entry of node.entries) {
+          defs.push({ key: entry.key, lineStart: entry.lineStart, lineEnd: entry.lineEnd });
+        }
+      }
+      if (node.children) walk(node.children);
+      if (node.type === "list" && node.items) walk(node.items);
+    }
+  }
+  walk(nodes);
+  return defs;
 }
 
 function validateRefs(nodes, options = {}) {
@@ -3117,6 +3449,43 @@ function validateRefs(nodes, options = {}) {
   return warnings;
 }
 
+function validateCitations(nodes) {
+  const { citationRefs } = collectInlineRefs(nodes);
+  const defs = collectCitationDefinitions(nodes);
+  const warnings = [];
+
+  const definedKeys = new Set(defs.map((d) => d.key));
+  const referencedKeys = new Set(citationRefs.map((r) => r.key));
+
+  // Citation referenced but not defined
+  for (const ref of citationRefs) {
+    if (!definedKeys.has(ref.key)) {
+      warnings.push({
+        type: "broken-citation",
+        key: ref.key,
+        message: `Broken citation: [@${ref.key}] is not defined in any {[citations] block`,
+        lineStart: ref.lineStart,
+        lineEnd: ref.lineEnd
+      });
+    }
+  }
+
+  // Citation defined but never referenced
+  for (const def of defs) {
+    if (!referencedKeys.has(def.key)) {
+      warnings.push({
+        type: "unused-citation",
+        key: def.key,
+        message: `Unused citation: @${def.key} is defined but never referenced with [@${def.key}]`,
+        lineStart: def.lineStart,
+        lineEnd: def.lineEnd
+      });
+    }
+  }
+
+  return warnings;
+}
+
 async function resolveIncludes(nodes, resolverFn) {
   for (const node of nodes) {
     if (node.type === "code" && node.src) {
@@ -3167,7 +3536,9 @@ module.exports = {
   // Validation
   collectAllIds,
   collectInlineRefs,
+  collectCitationDefinitions,
   validateRefs,
+  validateCitations,
   // Low-level helpers for custom renderers (e.g. slide-renderer)
   parseInline,
   renderKatex,