{"id":45733642,"url":"https://github.com/entropicwarrior/sdoc","last_synced_at":"2026-04-01T18:26:53.771Z","repository":{"id":340219832,"uuid":"1141050274","full_name":"entropicwarrior/sdoc","owner":"entropicwarrior","description":"Better Docs for Humans and AI Agents","archived":false,"fork":false,"pushed_at":"2026-03-28T09:17:22.000Z","size":2287,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-03-28T13:50:35.092Z","etag":null,"topics":["artificial-intelligence","documentation","llm","mcp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/entropicwarrior.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-24T06:35:09.000Z","updated_at":"2026-03-28T09:17:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/entropicwarrior/sdoc","commit_stats":null,"previous_names":["entropicwarrior/sdoc"],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/entropicwarrior/sdoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entropicwarrior%2Fsdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entropicwarrior%2Fsdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entropicwarrior%2Fsdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entropicwarrior%2Fsdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/entropicwarrior","download_url":"https://codeload.github.com/entropicwarrior/sdoc/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/entropicwarrior%2Fsdoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290852,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","documentation","llm","mcp"],"created_at":"2026-02-25T10:16:33.489Z","updated_at":"2026-04-01T18:26:53.760Z","avatar_url":"https://github.com/entropicwarrior.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SDOC\n\nA 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.\n\n## Why SDOC?\n\nMarkdown has no formal structure — section boundaries are ambiguous, extraction requires heuristics, and AI agents waste tokens loading entire files to find one section. SDOC fixes this.\n\n- **Unambiguous structure** — `{ }` braces define scope, not whitespace or heading levels. No guessing where a section ends.\n- **Progressive disclosure** — AI agents can read a table of contents, then extract only the sections they need. No need to consume the whole file.\n- **Unlimited nesting** — Nest scopes as deep as you like. Structure follows your content, not format limitations.\n- **Parsing safety** — Deterministic parsing eliminates the ambiguity that creates injection surfaces in automated document processing pipelines.\n- **Content-presentation separation** — The AST is format-neutral. Render to HTML, slides, PDF, or anything else from the same source.\n- **Human-readable as plain text** — No build step required to read an SDOC file. It looks good in any text editor.\n\n## What's in the Box\n\n**The format** — a formal specification (`lexica/specification.sdoc`) with EBNF grammar, plus a comprehensive authoring guide written as an AI agent skill document. Drop `docs/reference/sdoc-authoring.sdoc` into any AI agent's context and it can read and write SDOC immediately.\n\n**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.\n\n**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.\n\n**A document site builder** — serve a folder of SDOC files as a browsable site with sidebar navigation, search, and split-pane comparison.\n\n**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.\n\n**A VS Code extension** — live preview, sticky scroll, code folding, document symbols, mermaid/SVG rendering, and commands for all the above.\n\n## Quick Start\n\n### Install from the VS Code Marketplace\n\nSearch for **\"SDOC - Docs for Human/Agent Teams\"** by **Entropic Warrior MS Enfin** in the VS Code Extensions panel, or install from the command line:\n\n```bash\ncode --install-extension entropicwarrior-msenfin.vscode-sdoc\n```\n\nThis gives you automatic updates. If you previously installed from a `.vsix` file, uninstall that version first to avoid conflicts.\n\n### Build from source\n\n```bash\nnpm install\nnpm run package\ncode --install-extension dist/sdoc-*.vsix\n```\n\nOpen 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.\n\n### Build slides\n\n```bash\nnode tools/build-slides.js deck.sdoc -o slides.html\n```\n\nEach top-level scope becomes a slide. Set `type: slides` in `@meta`. See `docs/reference/slide-authoring.sdoc` for the full authoring guide.\n\n### Export to PDF or HTML\n\n```bash\nnode tools/build-doc.js doc.sdoc                   # PDF (requires Chrome)\nnode tools/build-doc.js doc.sdoc --html -o doc.html # HTML\n```\n\nOr use **SDOC: Export PDF** / **SDOC: Export HTML** from the VS Code Command Palette.\n\n### Browse documents\n\n```bash\npython3 tools/serve_docs.py docs/\n```\n\nOr use the **SDOC: Browse Documents** command from the VS Code Command Palette.\n\n## For AI Agents\n\nThis repo provides an [`llms.txt`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/llms.txt) file at the repo root for AI agent discovery.\n\nKey resources for agents:\n\n| Resource | What it gives you |\n|---|---|\n| [`docs/reference/sdoc-authoring.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/docs/reference/sdoc-authoring.sdoc) | Skill document — drop into context to read/write SDOC immediately |\n| [`lexica/specification.sdoc`](https://raw.githubusercontent.com/entropicwarrior/sdoc/main/lexica/specification.sdoc) | Formal spec with EBNF grammar |\n\nAll `.sdoc` files are designed for progressive disclosure. The JavaScript API provides three functions that let agents navigate without loading entire files:\n\n```javascript\nconst { extractAbout, listSections, extractSection } = require(\"@entropicwarrior/sdoc\");\n\nextractAbout(text);              // ~50 tokens — what is this file about?\nlistSections(text);              // ~50-100 tokens — what sections does it have?\nextractSection(text, \"error-handling\"); // ~200-1000 tokens — give me just this section\n```\n\nTotal cost for a precise answer: ~750 tokens. The same lookup in Markdown requires loading the full file (5,000-50,000 tokens).\n\n## Format at a Glance\n\n```sdoc\n# Chapter One @chapter-1\n{\n    This is body text with *emphasis*, **strong**, and `code`.\n\n    # Nested Section @details\n    {\n        Unlimited nesting. Each scope is independently addressable.\n\n        ```python\n        def hello():\n            print(\"Hello from SDOC\")\n        ```\n    }\n\n    # Status :example\n    {\n        {[table 60% center]\n            Endpoint | Status\n            /v2/api | {+Active+}\n            /v1/api | {-Deprecated-}\n        }\n    }\n\n    # Internal Notes :comment\n    {\n        This scope is invisible in rendered output but\n        stays in the AST for tooling and agents.\n    }\n}\n```\n\n## Features\n\n### Inline Formatting\n\n`*emphasis*`, `**strong**`, `~~strikethrough~~`, `` `inline code` ``, `[links](url)`, and `\u003chttps://autolinks\u003e`.\n\n### Semantic Markers\n\nAnnotate text with semantic meaning that renders as colored highlights:\n\n| Syntax | Meaning | Color |\n|---|---|---|\n| `{+text+}` | Positive | Green |\n| `{=text=}` | Neutral | Blue |\n| `{^text^}` | Note | Amber |\n| `{?text?}` | Caution | Dark amber |\n| `{!text!}` | Warning | Orange |\n| `{-text-}` | Negative | Red |\n| `{~text~}` | Highlight | Yellow |\n\nMarkers nest with other inline formatting: `{+**all checks** passed+}`.\n\n### Math\n\nInline math with `$x^2 + y^2$`, display math with `$$E = mc^2$$`, and multi-line equations with ` ```math ` code fences. Rendered via KaTeX.\n\n### Code Blocks\n\nFenced with triple backticks, optional language tag for syntax highlighting. The `src:` directive includes external files inline:\n\n````\n```json src:./config.json lines:1-10\n```\n````\n\n### Mermaid Diagrams\n\nCode blocks tagged `mermaid` render as SVG diagrams — flowcharts, sequence diagrams, class diagrams, state diagrams, and more.\n\n### SVG Diagrams\n\nCode blocks tagged `svg` render as inline SVG graphics, giving full control over shapes, layout, and styling. `\u003cscript\u003e` and `\u003cforeignObject\u003e` tags are stripped for security.\n\n### Images\n\nMarkdown-style images with optional width and alignment:\n\n```\n![Photo](image.png =50% center)\n```\n\n### Tables\n\nPipe-delimited tables with optional flags for appearance (`borderless`, `headerless`), width (`auto`, `60%`, `400px`), and alignment (`left`, `center`, `right`). All flags compose freely. Cells starting with `=` are evaluated as formulas (`=SUM`, `=AVG`, `=COUNT`, arithmetic with A1 cell references).\n\n### Lists\n\nBullet lists (`-`), numbered lists (`1.`), and task lists (`- [ ]` / `- [x]`). Items can have rich body content including nested lists, code blocks, and paragraphs.\n\n### References\n\nTag any section with `@id` and cross-reference it anywhere with `@id` — renders as a clickable link.\n\n### Slides\n\nTurn any SDOC file into an HTML slide deck with themes, layouts (center, two-column), speaker notes, and PDF export.\n\n### Scope Types\n\nClassify scopes with a `:type` annotation — `:schema`, `:warning`, `:deprecated`, `:example`, or any custom label. Types render as `data-scope-type` attributes and CSS classes for styling.\n\n### Data Blocks\n\nTag a JSON code fence with `:data` and the parser validates and stores the parsed result on the AST node. `extractDataBlocks()` gives programmatic access. Ideal for embedding schemas, configs, and structured metadata alongside prose.\n\n### Comment Scopes\n\nA `:comment` scope is excluded from rendered output but stays in the AST — perfect for agent instructions, internal notes, and build metadata that readers shouldn't see.\n\n### Custom Styling\n\nPer-folder `sdoc.config.json` or per-file `@meta` scope for custom CSS, headers, footers, and confidentiality banners. Configs cascade from workspace root to file.\n\n## Learning the Format\n\n- `docs/guide/intro.sdoc` — what SDOC is and why\n- `docs/guide/why-sdoc.sdoc` — the case for SDOC over Markdown\n- `docs/tutorials/first-steps.sdoc` — write your first document\n- `docs/reference/sdoc-authoring.sdoc` — authoring guide with quick reference and common mistakes\n- `docs/reference/syntax.sdoc` — full syntax reference\n\n## Contributing\n\nThis project uses **Git Flow**:\n\n| Branch | Purpose |\n|---|---|\n| `main` | Stable releases, tagged with version numbers |\n| `develop` | Integration branch — features merge here |\n| `release/vX.Y.Z` | Cut from `develop` when ready to release |\n| `feat/*`, `fix/*` | Short-lived branches off `develop` |\n\n**To contribute:**\n\n1. Create a branch off `develop` (`feat/my-feature`, `fix/parser-bug`, etc.)\n2. Make your changes, commit, push\n3. Open a PR targeting `develop`\n4. Get one approval from another contributor\n5. Merge (squash or regular — your call)\n\nRelease branches merge to both `main` and `develop`. No direct pushes to `main` or `develop`.\n\n## License\n\n[MIT](LICENSE) — 2026 @entropicwarrior\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fentropicwarrior%2Fsdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fentropicwarrior%2Fsdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fentropicwarrior%2Fsdoc/lists"}