@entropicwarrior/sdoc 0.2.2 → 0.2.4

package/docs/reference/sdoc-authoring.sdoc

@@ -265,6 +265,15 @@ Content of Section B.
             ```
 
             Width: \`auto\` (shrink to content), \`NN%\` (percentage), or \`NNpx\` (pixels). Default is 100%. Alignment: \`left\` (default), \`center\`, or \`right\`. All flags compose freely in any order.
+
+            To include a literal \`|\` in a cell (e.g. for math), escape it with \`\\|\`:
+
+            ```
+            {[table]
+                Expression | Value
+                \|x\| + \|y\| | 8
+            }
+            ```
         }
 
         # Inline Formatting @inline-formatting
@@ -307,7 +316,7 @@ Content of Section B.
 
         # References @references
         {
-            Assign a slug with \`@slug\` on a heading, then reference it anywhere with \`@slug\`:
+            Assign a slug with \`@slug\` on a heading, then reference it elsewhere in the same document with \`@slug\`:
 
             ```
             # Setup @setup {
@@ -318,6 +327,14 @@ Content of Section B.
                 Make sure you complete @setup first.
             }
             ```
+
+            References are **document-local only** — \`@slug\` resolves within the current file. To point a reader to a section in another file, use a link with a fragment:
+
+            ```
+            See [Setup](./other-file.sdoc#setup) for details.
+            ```
+
+            Do not write \`@setup\` when the target scope is in a different file — it will be flagged as a broken reference.
         }
 
         # Code Blocks @code-blocks
@@ -462,7 +479,7 @@ Content of Section B.
         {
             Backslash escapes special characters: \`\\\\\` \`\\{\` \`\\}\` \`\\@\`
             \`\\[\` \`\\]\` \`\\(\` \`\\)\` \`\\*\` \`\\~\` \`\\#\` \`\\!\` \`\\\<\`
-            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\` \`\\^\` \`\\?\`
+            \`\\\>\` \`\\\$\` \`\\+\` \`\\=\` \`\\-\` \`\\^\` \`\\?\` \`\\|\`
 
             A line starting with \`\\#\` renders as a literal \`#\` (not a heading). Use \`\\\$\` to prevent a dollar sign from starting math mode.
         }
@@ -672,6 +689,25 @@ Content of Section B.
             ```
         }
 
+        # Cross-Document @slug References @cross-doc-refs
+        {
+            \`@slug\` references are document-local. Using \`@slug\` to refer to a section in another file produces a broken reference error:
+
+            **Wrong** — \`@setup\` does not exist in this file:
+
+            ```
+            See `getting-started.sdoc` @setup for installation steps.
+            ```
+
+            **Right** — use a link with a fragment:
+
+            ```
+            See [Setup](./getting-started.sdoc#setup) for installation steps.
+            ```
+
+            The fragment (\`#setup\`) matches the target scope's \`@id\`. Use \`\\@\` if you need a literal \`@\` in text without triggering reference resolution.
+        }
+
         # @References Inside Link Labels @refs-in-link-labels
         {
             Inline \`@references\` are parsed everywhere, including inside link labels. If you mention a scope ID in a link label, escape the \`@\` to prevent it being treated as a reference to the current document:

package/lexica/specification.sdoc

@@ -393,6 +393,8 @@ Content of Section B.
         {
             {[.]
                 - A reference is `@id` in text (unescaped)
+                - References are document-local: `@id` resolves to a scope within the same file only. Cross-document reference syntax may be introduced in a future version but is not part of v0.2
+                - To link to a section in another file, use a standard link with a fragment: `[Label](./other-file.sdoc#section-id)`
                 - References link to the scope with that ID
                 - ID uniqueness is strongly recommended; tooling may warn on duplicates
                 - References are parsed inside link labels — use `\@` to include a literal `@` in a link label without triggering a reference
@@ -508,11 +510,11 @@ Content of Section B.
 
         # Escaping @escaping
         {
-            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` `\^` `\?` and `` \` ``.
+            In normal text (including headings and paragraphs), a backslash escapes: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` `\+` `\=` `\-` `\^` `\?` `\|` and `` \` ``.
 
             Escapes are processed before reference detection.
 
-            If a line begins with `\#`, it is treated as a normal paragraph line (rendered with a literal `#`). If a line begins with `\>`, it is treated as a normal paragraph line (rendered with a literal `>`). Use `\$` to prevent a dollar sign from starting math mode.
+            If a line begins with `\#`, it is treated as a normal paragraph line (rendered with a literal `#`). If a line begins with `\>`, it is treated as a normal paragraph line (rendered with a literal `>`). Use `\$` to prevent a dollar sign from starting math mode. Use `\|` to include a literal pipe character inside a table cell without it being treated as a column delimiter.
         }
 
         # Code Blocks @code-blocks

package/package.json

@@ -2,7 +2,7 @@
   "name": "@entropicwarrior/sdoc",
   "displayName": "SDOC",
   "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.2",
+  "version": "0.2.4",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {

package/src/sdoc.js

@@ -13,7 +13,7 @@ const COMMAND_LIST_NUMBER = "{[#]";
 const COMMAND_TABLE = "{[table]";
 const COMMAND_CODE_FENCE = "```";
 
-const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-", "^", "?"]);
+const ESCAPABLE = new Set(["\\", "{", "}", "@", "[", "]", "(", ")", "*", "`", "#", "!", "~", "<", ">", "$", "+", "=", "-", "^", "?", "|"]);
 
 let _katex = null;
 let _katexLoaded = false;
@@ -797,7 +797,7 @@ function parseTableBody(cursor, tableStartLine, options) {
       break;
     }
 
-    const cells = trimmed.split("|").map((cell) => cell.trim());
+    const cells = trimmed.split(/(?<!\\)\|/).map((cell) => cell.trim().replace(/\\\|/g, "|"));
     rows.push(cells);
     cursor.next();
   }