github-linguist / github-linguist/linguist
Add SDOC language recognition (.sdoc)
- Dominant language
- Ruby
- Stars
- 13.7k
- Forks
- 5.4k
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 17
Description
## Language information
- **Name**: SDOC
- **Extension**: `.sdoc` (unique — no overlap with other languages)
- **Type**: Prose / markup
- **Repository**: [github.com/entropicwarrior/sdoc](https://github.com/entropicwarrior/sdoc)
- **Specification**: [lexica/specification.sdoc](https://github.com/entropicwarrior/sdoc/blob/main/lexica/specification.sdoc)
## What is SDOC?
SDOC is a documentation format designed for human/AI collaboration. The raw format reads like clean plain text — both humans and AI agents can author and edit it fluently. Rendered, it produces rich documents with collapsible sections, tables, images, math, mermaid diagrams, and syntax-highlighted code blocks.
The defining feature is explicit brace scoping: `{ }` braces mark section boundaries unambiguously. Every document has exactly one valid parse tree. This lets AI agents surgically extract or modify a single section without loading the entire file — a significant efficiency gain over formats like Markdown where section boundaries require heuristics.
## Sample
```
# Project Overview @overview {
A documentation format where humans and AI agents
collaborate on the same source files.
# Features {
- Explicit brace scoping — no ambiguous boundaries
- Rich rendering — tables, images, math, diagrams
- Progressive disclosure — read headings first, load sections on demand
- Zero-dependency JavaScript parser
}
# Status :example {
{[table auto center]
Component | Status
Parser | Complete
Renderer | Complete
VS Code Extension | Published
}
}
}
```
## Extension uniqueness
The `.sdoc` extension is not used by any language currently in Linguist. No disambiguation heuristics are needed.
## Sample files
Sample files are available in the repository:
- [examples/example.sdoc](https://github.com/entropicwarrior/sdoc/blob/main/examples/example.sdoc) — comprehensive feature showcase
- [docs/reference/sdoc-authoring.sdoc](https://github.com/entropicwarrior/sdoc/blob/main/docs/reference/sdoc-authoring.sdoc) — authoring reference
- [lexica/specification.sdoc](https://github.com/entropicwarrior/sdoc/blob/main/lexica/specification.sdoc) — formal specification
## Current adoption
SDOC is early in adoption. We have a published npm package ([@entropicwarrior/sdoc](https://www.npmjs.com/package/@entropicwarrior/sdoc)), a VS Code extension, and are actively growing usage. We understand the usage thresholds for language addition and are happy to revisit when `.sdoc` files reach sufficient numbers on GitHub. Opening this issue to start the conversation and get feedback on what's needed.
## TextMate grammar
A TextMate grammar for syntax highlighting is available at [syntaxes/sdoc.tmLanguage.json](https://github.com/entropicwarrior/sdoc/blob/main/syntaxes/sdoc.tmLanguage.json).
Contributor guide
Assessment
This issue has not been assessed yet.