SDOC

A plain-text documentation format designed for AI-agent efficiency. Explicit brace scoping means deterministic parsing, surgical section extraction, and 10-50x token savings compared to Markdown.

Why SDOC?

• Unambiguous structure — { } braces define scope, not whitespace or heading levels. No guessing where a section ends.
• Progressive disclosure — AI agents can read a table of contents, then extract only the sections they need. No need to consume the whole file.
• Unlimited nesting — Nest scopes as deep as you like. Structure follows your content, not format limitations.
• Content-presentation separation — The AST is format-neutral. Render to HTML, slides, PDF, or anything else from the same source.
• Human-readable as plain text — No build step required to read an SDOC file. It looks good in any text editor.

What's in the Box

The format — a formal specification (lexica/specification.sdoc) with EBNF grammar, plus a comprehensive authoring guide written as an AI agent skill document. Drop lexica/sdoc-authoring.sdoc into any AI agent's context and it can read and write SDOC immediately.

A zero-dependency JavaScript parser — src/sdoc.js parses SDOC into a format-neutral AST. No runtime dependencies, works anywhere Node runs. Parsing and rendering are cleanly separated — build your own renderers on top.

Slide deck generation — turn any SDOC file into an HTML slide deck with themes, layouts (center, two-column), speaker notes, mermaid diagrams, and PDF export via headless Chrome.

A document site builder — serve a folder of SDOC files as a browsable site with sidebar navigation, search, and split-pane comparison.

PDF and HTML export — export any document to A4 PDF via headless Chrome, or to standalone HTML. Available as both a CLI tool and a VS Code command.

A VS Code extension — live preview, sticky scroll, code folding, document symbols, mermaid rendering, and commands for all the above.

Quick Start

# Build and install the VS Code extension
npm install
npm run package
code --install-extension dist/sdoc-*.vsix

Open any .sdoc file and click the preview icon in the editor title bar, or run SDOC: Open Preview to the Side from the Command Palette.

Build slides

node tools/build-slides.js deck.sdoc -o slides.html

Each top-level scope becomes a slide. Set type: slides in @meta. See lexica/slide-authoring.sdoc for the full authoring guide.

Export to PDF or HTML

node tools/build-doc.js doc.sdoc                   # PDF (requires Chrome)
node tools/build-doc.js doc.sdoc --html -o doc.html # HTML

Or use SDOC: Export PDF / SDOC: Export HTML from the VS Code Command Palette.

Browse documents

python3 tools/serve_docs.py docs/

Or use the SDOC: Browse Documents command from the VS Code Command Palette.

Format at a Glance

# Chapter One @chapter-1
{
    This is body text with *emphasis*, **strong**, and `code`.

    # Nested Section @details
    {
        Unlimited nesting. Each scope is independently addressable.

        {[code lang=python]
            def hello():
                print("Hello from SDOC")
        }
    }

    # A List
    {
        {[.]
            - First item
            - Second item with **bold**
            - Third item
        }
    }
}

Features

Inline Formatting

*emphasis*, **strong**, ~~strikethrough~~, `inline code`, [links](url), and <https://autolinks>.

Semantic Markers

Annotate text with semantic meaning that renders as colored highlights:

| Syntax | Meaning | Color | |---|---|---| | {+text+} | Positive | Green | | {=text=} | Neutral | Blue | | {^text^} | Note | Amber | | {?text?} | Caution | Dark amber | | {!text!} | Warning | Orange | | {-text-} | Negative | Red | | {~text~} | Highlight | Yellow |

Markers nest with other inline formatting: {+**all checks** passed+}.

Math

Inline math with $x^2 + y^2$, display math with $$E = mc^2$$, and multi-line equations with ```math code fences. Rendered via KaTeX.

Code Blocks

Fenced with triple backticks, optional language tag for syntax highlighting. The src: directive includes external files inline:

```json src:./config.json lines:1-10
```

Mermaid Diagrams

Code blocks tagged mermaid render as SVG diagrams — flowcharts, sequence diagrams, class diagrams, state diagrams, and more.

Images

Markdown-style images with optional width and alignment:

![Photo](image.png =50% center)

Tables

Pipe-delimited tables with optional borderless and headerless flags.

Lists

Bullet lists (-), numbered lists (1.), and task lists (- [ ] / - [x]). Items can have rich body content including nested lists, code blocks, and paragraphs.

References

Tag any section with @id and cross-reference it anywhere with @id — renders as a clickable link.

Slides

Turn any SDOC file into an HTML slide deck with themes, layouts (center, two-column), speaker notes, and PDF export.

Custom Styling

Per-folder sdoc.config.json or per-file @meta scope for custom CSS, headers, footers, and confidentiality banners. Configs cascade from workspace root to file.

Learning the Format

• docs/guide/intro.sdoc — what SDOC is and why
• docs/tutorials/first-steps.sdoc — write your first document
• docs/reference/syntax.sdoc — full syntax reference
• SDOC_GUIDE.md — quick reference in Markdown (also used by AI tools)

Contributing

This project uses Git Flow:

| Branch | Purpose | |---|---| | main | Stable releases, tagged with version numbers | | develop | Integration branch — features merge here | | release/vX.Y.Z | Cut from develop when ready to release | | feat/*, fix/* | Short-lived branches off develop |

To contribute:

1. Create a branch off develop (feat/my-feature, fix/parser-bug, etc.)
2. Make your changes, commit, push
3. Open a PR targeting develop
4. Get one approval from another contributor
5. Merge (squash or regular — your call)

Release branches merge to both main and develop. No direct pushes to main or develop.

License

MIT — 2026 @entropicwarrior