github-linguist / github-linguist/linguist

Add SDOC language recognition (.sdoc)

Open
#7,838 1 comment 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.