@entropicwarrior/sdoc 0.1.14 → 0.1.17

package/docs/reference/syntax.sdoc

@@ -0,0 +1,502 @@
+# Syntax Reference
+{
+    @meta {
+        sdoc-version: 0.1
+    }
+
+    This is a practical reference for writing SDOC files. For the formal specification (edge cases, grammar, parsing rules), see \`lexica/specification.sdoc\`.
+
+    # Scopes
+    {
+        A scope is a heading line followed by a brace-delimited block:
+
+        ```
+# Heading @optional-id
+{
+    Body content here.
+}
+        ```
+
+        {[.]
+            - The heading starts with `#` (after optional indentation)
+            - Multiple `#` characters are allowed but do not affect depth; depth comes from nesting
+            - The optional `@id` must be the last token on the heading line, separated by whitespace
+            - IDs may contain letters, digits, underscores, and hyphens (must start with a letter or underscore)
+        }
+
+        In the VSCode interactive preview, scopes with children display a collapsible toggle triangle on hover. Clicking the triangle collapses or expands the scope's children. Collapse state persists across preview refreshes.
+
+        # Braceless Scopes
+        {
+            A heading not followed by `{` or a block opener creates a braceless scope. Content runs until the next `#` heading, a closing `}`, or end of file:
+
+            ```
+# Section A
+Content of Section A.
+
+# Section B
+Content of Section B.
+            ```
+
+            {[.]
+                - Braceless scopes support paragraphs, code blocks, blockquotes, implicit lists, HRs, and tables
+                - Encountering another `#` heading ends the braceless scope (the heading becomes a sibling)
+                - A closing `}` also terminates a braceless scope
+                - Braceless and explicit scopes can be mixed freely
+            }
+        }
+
+        # Headingless Scopes
+        {
+            A bare `{` block without a preceding heading creates a scope with no heading:
+
+            ```
+# Outer
+{
+    Some text.
+
+    {
+        This content is indented one level deeper, with no heading.
+    }
+}
+            ```
+
+            Headingless scopes nest like normal scopes and are useful for grouping paragraphs or adding visual indentation without a title.
+        }
+
+        # K&R Brace Style
+        {
+            The opening brace (or list/table opener) can appear at the end of a heading line:
+
+            ```
+# Title {
+    Content goes here.
+}
+
+# My List {[.]
+    - Item 1
+    - Item 2
+}
+
+# Data {[table]
+    Name | Age
+    Alice | 30
+}
+            ```
+
+            {[.]
+                - Works with `{`, `{[.]`, `{[#]`, `{[table]`, and `{[table <flags>]`
+                - Also works on list item lines: `- Item {`
+                - The `@id` goes before the opener: `# Title @id {`
+                - Table options work in K&R style: `# Data {[table borderless]`
+                - Trailing whitespace after the opener is allowed
+                - The closing `}` must still appear on its own line
+                - Inline blocks (`{ content }`) are not affected
+            }
+
+            K&R and Allman styles can be mixed freely in the same document.
+        }
+
+        # Inline Blocks
+        {
+            For simple content, a scope body can be written on one line:
+
+            ```
+# Name
+{ John Doe }
+
+# Count
+{ 42 }
+            ```
+
+            Inline blocks must not contain unescaped `{` or `}` characters.
+        }
+    }
+
+    # Paragraphs
+    {
+        Consecutive text lines are joined into a single paragraph. A blank line, a new scope, or a list ends the current paragraph.
+
+        ```
+# Example
+{
+    This is one paragraph
+    that spans two lines.
+
+    This is a second paragraph.
+}
+        ```
+    }
+
+    # Lists
+    {
+        # Explicit Lists
+        {
+            Use `{[.]` for bulleted lists and `{[#]` for numbered lists:
+
+            ```
+# Fruits
+{[.]
+    - Apples
+    - Bananas
+    - Cherries
+}
+
+# Steps
+{[#]
+    1. First step
+    2. Second step
+    3. Third step
+}
+            ```
+
+            List items can have bodies:
+
+            ```
+{[.]
+    - Item title
+    {
+        Body text for this item.
+    }
+}
+            ```
+
+            Commas between list items are allowed but ignored.
+        }
+
+        # Multi-line List Items
+        {
+            Inside an explicit list block (`{[.]` or `{[#]`), a list item's title can span multiple lines. Lines after the marker that aren't a command token are joined with a space:
+
+            ```
+{[.]
+    - This is a long list item
+      that continues on the next line
+    - Short item
+}
+            ```
+
+            Continuation stops at blank lines, list markers, headings, braces, code fences, blockquotes, and horizontal rules. A body block can still follow the completed multi-line title. This only applies to explicit list blocks, not implicit lists.
+        }
+
+        # Implicit Lists
+        {
+            Inside a normal scope, a run of `- ` lines automatically forms a bulleted list, and a run of `1. ` lines forms a numbered list:
+
+            ```
+# Notes
+{
+    - First point
+    - Second point
+    - Third point
+}
+            ```
+
+            Mixed markers end the implicit list.
+        }
+
+        # Task Lists
+        {
+            Checkboxes work inside list blocks:
+
+            ```
+{[.]
+    - [ ] Pending task
+    - [x] Completed task
+}
+            ```
+        }
+
+        # Anonymous List Items
+        {
+            A list item can start with a block directly, without a heading:
+
+            ```
+{[.]
+    {
+        This item has no heading line.
+    }
+}
+            ```
+        }
+    }
+
+    # Tables
+    {
+        Use `{[table]` to create a table. The first row is the header:
+
+        ```
+{[table]
+    Name | Age | City
+    Alice | 30 | New York
+    Bob | 25 | Los Angeles
+}
+        ```
+
+        {[.]
+            - Columns are separated by `|`
+            - The first row is always the header (unless `headerless` is specified)
+            - Cell contents support inline formatting
+            - Leading and trailing whitespace in cells is trimmed
+        }
+
+        # Table Options
+        {
+            Add flags after `table` to control rendering:
+
+            ```
+{[table borderless]
+    Feature | Status
+    Parser | Complete
+    Renderer | Complete
+}
+
+{[table headerless]
+    Alice | 30 | New York
+    Bob | 25 | Los Angeles
+}
+
+{[table borderless headerless]
+    ![](a.png =100%) | ![](b.png =100%)
+    ![](c.png =100%) | ![](d.png =100%)
+}
+            ```
+
+            {[.]
+                - `borderless` removes all borders and row striping
+                - `headerless` treats the first row as data (no header)
+                - Flags can be combined in any order
+                - Works with K&R brace style: `# Data {[table borderless]`
+            }
+        }
+    }
+
+    # Inline Formatting
+    {
+        {[.]
+            - `*emphasis*` renders as *emphasis*
+            - `**strong**` renders as **strong**
+            - `~~strikethrough~~` renders as ~~strikethrough~~
+            - `` `code` `` renders as `code`
+            - `$x^2$` renders as inline math (KaTeX)
+            - `$$E = mc^2$$` renders as display math (centered)
+            - `{+text+}` renders as {+positive (green) marker+}
+            - `{=text=}` renders as {=neutral (blue) marker=}
+            - `{^text^}` renders as {^note (amber) marker^}
+            - `{?text?}` renders as {?caution (dark amber) marker?}
+            - `{!text!}` renders as {!warning (orange) marker!}
+            - `{-text-}` renders as {-negative (red) marker-}
+            - `{~text~}` renders as {~highlighted text~}
+        }
+
+        A plain `$` followed by a digit (e.g. `$100`) does not trigger math. Use `\$` to escape dollar signs adjacent to math.
+    }
+
+    # Links and Images
+    {
+        # Links
+        {
+            ```
+[Link text](https://example.com)
+            ```
+        }
+
+        # Autolinks
+        {
+            ```
+<https://example.com>
+<mailto:hello@example.com>
+            ```
+
+            Only `http`, `https`, and `mailto` schemes are recognised.
+        }
+
+        # Images
+        {
+            ```
+![Alt text](https://example.com/image.png)
+            ```
+
+            # Image Width and Alignment
+            {
+                Add `=<width>` after the URL (separated by a space) to control size. An optional alignment keyword follows:
+
+                ```
+![Photo](photo.png =50%)
+![Photo](photo.png =200px)
+![Photo](photo.png =50% center)
+![Photo](photo.png =35% left)
+![Photo](photo.png =35% right)
+                ```
+
+                {[.]
+                    - `center` centres the image with auto margins
+                    - `left` floats the image left (text wraps right)
+                    - `right` floats the image right (text wraps left)
+                    - Without alignment, images display inline — two adjacent images with widths sit side by side
+                }
+            }
+        }
+    }
+
+    # References
+    {
+        Tag a scope with `@id` on its heading line, then reference it anywhere with `@id` in text:
+
+        ```
+# Overview @overview
+{
+    This section is tagged.
+}
+
+# Details
+{
+    See @overview for the introduction.
+}
+        ```
+
+        References render as clickable links to the target scope.
+    }
+
+    # Blockquotes
+    {
+        Lines starting with `>` form a blockquote:
+
+        ```
+> A quoted line.
+> Another line in the same quote.
+        ```
+
+        A blank `>` line breaks paragraphs within the blockquote. Escape with `\>` to use a literal `>` at the start of a line.
+    }
+
+    # Code Blocks
+    {
+        Fenced code blocks use three backticks to delimit raw text. An optional language tag follows the opening fence.
+
+        {[.]
+            - Opening fence: three backticks, optionally followed by a language name (e.g. `javascript`, `python`)
+            - Closing fence: three backticks on their own line
+            - Content inside is raw text -- no parsing, no escapes, no inline formatting
+            - Braces, `#`, `@`, and all other special characters are treated as literal text inside code blocks
+            - The special language tag `math` renders the block as a display equation via KaTeX (no copy button)
+            - The special language tag `mermaid` renders the block as an SVG diagram
+        }
+
+        # Include by Link
+        {
+            A code block can reference an external file with `src:` metadata on the fence line. The file contents replace the code block body:
+
+            `````
+```json src:./data.json
+```
+
+```json src:./data.json lines:3-5
+```
+
+```src:https://example.com/schema.json
+```
+            `````
+
+            {[.]
+                - `src:<path>` references a file (relative to the document) or URL
+                - `lines:<start>-<end>` limits to a line range (1-based, inclusive)
+                - The language tag is optional and goes before `src:`
+                - If the file cannot be read, an error message is shown in the code block
+            }
+        }
+    }
+
+    # Horizontal Rules
+    {
+        A line of three or more identical characters (`-`, `*`, or `_`):
+
+        ```
+---
+        ```
+    }
+
+    # Escaping
+    {
+        A backslash escapes special characters: `\\` `\{` `\}` `\@` `\[` `\]` `\(` `\)` `\*` `\~` `\#` `\!` `\<` `\>` `\$` and `` \` ``.
+
+        {[.]
+            - `\#` at the start of a line makes it a paragraph line instead of a heading
+            - `\>` at the start of a line makes it a paragraph line instead of a blockquote
+            - `\$` prevents a dollar sign from starting math mode
+            - Escapes are processed before reference detection
+        }
+    }
+
+    # Implicit Root
+    {
+        If the first heading in a document is not followed by `{` or a block opener, the entire document is wrapped in an implicit root scope:
+
+        ```
+# My Document
+
+# Section A
+Content of section A.
+
+# Section B
+{
+    Content of section B.
+}
+        ```
+
+        This is equivalent to wrapping everything after the first heading in `{ ... }`. If the first heading IS followed by `{`, the document uses explicit root mode (existing behavior).
+    }
+
+    # Meta Scope
+    {
+        A reserved `@meta` scope at the top level overrides rendering options per file:
+
+        ```
+# Meta @meta
+{
+    # Style
+    { path/to/custom.css }
+    # StyleAppend
+    { path/to/overrides.css }
+    # Header
+    { My *custom* header }
+    # Footer
+    { Page-specific footer }
+}
+        ```
+
+        {[.]
+            - The `@meta` scope is not rendered in the document body
+            - `Style` and `StyleAppend` are file paths relative to the SDOC file
+            - `Header` and `Footer` support inline formatting
+            - Per-file meta overrides `sdoc.config.json` values
+        }
+
+        # Key:Value Meta Syntax
+        {
+            For simpler metadata, use key:value pairs instead of sub-scopes:
+
+            ```
+# Meta @meta
+{
+    style: path/to/custom.css
+    header: My Header
+    footer: My Footer
+    author: Jane Smith
+    date: 2026-02-09
+    version: 1.0
+    sdoc-version: 0.1
+}
+            ```
+
+            {[.]
+                - Key matching is case-insensitive
+                - Requires at least one space after the colon
+                - Well-known keys: `style`, `styleappend`/`style-append`, `header`, `footer`, `sdoc-version`
+                - `sdoc-version` identifies the format version (current: `0.1`); a warning is emitted when missing
+                - Other keys (e.g., `author`, `date`, `version`) are stored as custom properties
+                - Sub-scope syntax takes precedence over key:value when both exist
+            }
+        }
+    }
+}

package/docs/tutorials/first-steps.sdoc

@@ -0,0 +1,117 @@
+# First Steps with SDOC
+{
+    @meta {
+        sdoc-version: 0.1
+    }
+
+    # Step 1: Create a File
+    {
+        Create a new file with a `.sdoc` extension, for example `notes.sdoc`:
+
+        ```
+# My Notes
+
+Hello, this is my first SDOC document.
+        ```
+
+        The simplest SDOC file is just a heading followed by content. The heading becomes the document title and everything after it is the body (this is called an implicit root scope). You can also use explicit braces for more control:
+
+        ```
+# My Notes
+{
+    Hello, this is my first SDOC document.
+}
+        ```
+    }
+
+    # Step 2: Add Nested Sections
+    {
+        Add structure by nesting scopes inside the top-level block:
+
+        ```
+# My Notes
+{
+    # Introduction
+    {
+        This is the introduction.
+    }
+
+    # Details
+    {
+        Here are the details.
+    }
+}
+        ```
+
+        Each nested scope renders as a subsection with a smaller heading.
+    }
+
+    # Step 3: Preview in VS Code
+    {
+        Open your `.sdoc` file in VS Code and run the command **SDOC: Open Preview to the Side**. You should see a rendered view that updates as you type.
+    }
+
+    # Step 4: Add Formatting
+    {
+        Try adding inline formatting, math, and a list:
+
+        ```
+# My Notes
+{
+    # Introduction
+    {
+        SDOC supports *emphasis*, **strong**, `code`, ~~strikethrough~~, and math like $E = mc^2$.
+
+        Semantic markers: {+passed+}, {=info=}, {^note^}, {?caution?}, {!warning!}, {-failed-}, and {~highlighted~}.
+    }
+
+    # To Do
+    {[.]
+        - [ ] Learn the basics
+        - [ ] Write a real document
+        - [x] Install the extension
+    }
+}
+        ```
+    }
+
+    # Step 5: Use References
+    {
+        Tag sections with `@id` and cross-reference them:
+
+        ```
+# Overview @overview
+{
+    This section introduces the project.
+}
+
+# Details
+{
+    As described in @overview, the project has three parts.
+}
+        ```
+
+        The `@overview` in the text becomes a clickable link to the tagged section.
+    }
+
+    # Step 6: Add Blockquotes and Code
+    {
+        Blockquotes use `>` at the start of each line:
+
+        ```
+> Documentation is a love letter
+> that you write to your future self.
+        ```
+
+        Code blocks use three backticks as opening and closing fences, with an optional language tag. Everything inside is raw text -- braces, `#`, and `@` are not parsed.
+    }
+
+    # What's Next
+    {
+        {[.]
+            - Read `docs/reference/syntax.sdoc` for all available features
+            - Read `docs/reference/cli.sdoc` for the document server and CLI tools
+            - Look at `examples/example.sdoc` for a quick-reference document
+        }
+    }
+}

package/knowledge.js

@@ -1,2 +1,12 @@
 const path = require('path');
+
+// Knowledge files shipped with this package for consumption by MCP servers
+// and other knowledge infrastructure. Each entry has a cache key and absolute path.
+module.exports.knowledgeFiles = [
+  { key: 'specification.sdoc', path: path.join(__dirname, 'lexica', 'specification.sdoc') },
+  { key: 'sdoc-authoring.sdoc', path: path.join(__dirname, 'docs', 'reference', 'sdoc-authoring.sdoc') },
+  { key: 'slide-authoring.sdoc', path: path.join(__dirname, 'docs', 'reference', 'slide-authoring.sdoc') },
+];
+
+// Backward compat — prefer knowledgeFiles for explicit file enumeration
 module.exports.knowledgeDir = path.join(__dirname, 'lexica');

package/llms.txt

@@ -0,0 +1,20 @@
+# SDOC
+
+> A plain-text documentation format with explicit brace scoping. Deterministic parsing, surgical section extraction, and 10-50x token savings compared to Markdown. Zero-dependency JavaScript parser, VS Code extension, slide generation, and PDF export.
+
+SDOC uses `{ }` braces to define document structure explicitly. Two parsers, same input, same tree — always. AI agents can navigate an SDOC knowledge base in ~200 tokens of discovery, then extract exactly the section they need in ~200-1000 tokens, instead of loading entire files at 5,000-50,000 tokens each.
+
+The authoring guide (`docs/reference/sdoc-authoring.sdoc`) is written as an AI agent skill document. Drop it into any agent's context and it can read and write SDOC immediately.
+
+## Docs
+
+- [SDOC Authoring Guide](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc): Skill document — how to write correct SDOC files. Covers document structure, inline formatting, block types (lists, tables, code, blockquotes), mermaid diagrams, and common mistakes. Start here to learn the format.
+- [SDOC Specification](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc): Formal v0.1 specification with EBNF grammar. Defines syntax for scopes, lists, tables, code blocks, inline formatting, references, and the meta scope.
+- [Why SDOC Over Markdown](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/guide/why-sdoc.sdoc): The case for SDOC — structural problems with Markdown, why explicit scoping solves them, parsing safety as a security property, and the adoption path forward.
+
+## Optional
+
+- [Requirements](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/requirements.sdoc): Why SDOC exists and what it must achieve. Ten abstract requirements (R1-R10) and concrete constraints (C1-C6).
+- [Slide Authoring Guide](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/slide-authoring.sdoc): How to create HTML slide decks from SDOC files.
+- [Introduction](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/guide/intro.sdoc): Gentle introduction to the format for newcomers.
+- [Syntax Reference](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/syntax.sdoc): Practical syntax reference with examples.

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.1.14",
+  "version": "0.1.17",
   "publisher": "entropicwarrior",
   "license": "MIT",
   "repository": {