6533
Yo
yoctomarkdown / files
yoctomarkdown / spec.md
6.9 KB
1# YoctoMarkdown Specification 2 3YoctoMarkdown is a small Bun-native Markdown highlighter for terminal output. 4It reads Markdown and writes ANSI-colored text to stdout or returns it as a string. 5The focus is simple, fast, incremental rendering for CLI and Programmatic use. 6 7## Overview 8 9YoctoMarkdown MUST: 10 11- accept Markdown from a complete string, a file, or a stream 12- process input incrementally 13- render supported Markdown syntax as ANSI-styled terminal text 14- preserve unsupported or malformed Markdown as plain text 15- avoid buffering the document when used in streaming mode 16 17YoctoMarkdown is not a full CommonMark implementation. 18It supports a small, practical subset intended for terminal display. 19 20## Dependencies 21 22YoctoMarkdown is intended to use: 23 24- **Bun** as the runtime, stream, and build tool 25- **yoctocolors** from npm for ANSI color rendering - https://github.com/sindresorhus/yoctocolors 26 27## Supported Markdown 28 29Version 1 supports the following syntax: 30 31| Element | Syntax | Behavior | 32| ----------------- | ------------------ | ------------------ | 33| Heading 1 | `# Title` | styled heading | 34| Heading 2 | `## Title` | styled heading | 35| Heading 3 | `### Title` | styled heading | 36| Bold | `**text**` | styled inline text | 37| Italic | `*text*` | styled inline text | 38| Inline code | `` `code` `` | styled inline code | 39| Fenced code block | ` ``` ` | styled block code | 40| Link | `[text](url)` | styled link text | 41| Unordered list | `- item`, `* item` | styled marker | 42| Ordered list | `1. item` | styled marker | 43| Blockquote | `> quote` | styled marker | 44| Horizontal rule | `---` | styled rule | 45| Plain text | any other text | unchanged text | 46 47Unsupported syntax MUST be rendered as plain text. 48 49## Parsing Rules 50 51The parser is line-aware and incremental. 52 53### Block rules 54 55- Headings are recognized only at the start of a line. 56- Only `#`, `##`, and `###` headings are supported. 57- Fenced code blocks use triple backticks. 58- Inside a fenced code block, all text is treated as code until a closing triple backtick fence is found. 59- Horizontal rules are recognized only when the full trimmed line is `---`, `***`, or `___`. 60- List and blockquote markers are recognized only at the start of a line. 61 62### Inline rules 63 64- Inline code has priority over other inline formatting. 65- Links are recognized only in the form `[text](url)`. 66- Bold uses `**text**`. 67- Italic uses `*text*`. 68- Nested or ambiguous inline formatting is not required to match full CommonMark behavior. 69 70### Malformed input 71 72- Incomplete inline constructs MAY remain buffered while more input is expected. 73- At end of input, any unclosed inline construct MUST be emitted as plain text. 74- An unclosed fenced code block MUST render as code until end of input. 75 76## Streaming Behavior 77 78Streaming mode MUST work chunk by chunk. 79 80For each chunk: 81 821. append the chunk to an internal buffer 832. parse as much complete Markdown as possible 843. render completed output immediately 854. keep only unresolved trailing text in the buffer 86 87The implementation MUST preserve enough state to handle syntax split across chunk boundaries. 88 89## Rendering 90 91Rendering maps recognized Markdown elements to ANSI styles. 92 93The implementation MUST provide these built-in theme names: 94 95- `16` 96- `256` 97- `truecolor` 98- `minimal` 99- `none` 100 101Theme behavior: 102 103- headings MUST be visually distinct from plain text 104- bold and italic SHOULD be visually distinct from plain text 105- code and code blocks MUST be visually distinct from surrounding text 106- links SHOULD be visually distinct from plain text 107- list and blockquote markers MAY be styled independently 108- `none` MUST disable ANSI styling entirely 109 110The exact colors are implementation-defined. 111 112## Configuration 113 114The implementation MUST support the following options: 115 116```ts 117interface Options { 118 theme?: "16" | "256" | "truecolor" | "minimal" | "none" | Theme; 119 tabWidth?: number; 120 wordWrap?: number | "auto" | 0; 121 yieldEvery?: number; 122} 123``` 124 125Default values: 126 127- `theme`: `'16'` 128- `tabWidth`: `2` 129- `wordWrap`: `'auto'` 130- `yieldEvery`: `1000` 131 132### Word wrap 133 134If wrapping is enabled: 135 136- `'auto'` means terminal width when available, otherwise `80` 137- `0` disables wrapping 138- ANSI escape sequences MUST NOT count toward visible width 139 140## Library API 141 142The library MUST expose: 143 144```ts 145highlightSync(input: string, options?: Options): string 146createHighlighter(options?: Options): Highlighter 147``` 148 149```ts 150interface Highlighter { 151 write(chunk: string | Uint8Array): string; 152 end(): string; 153} 154``` 155 156Behavior: 157 158- `highlightSync()` returns the fully rendered ANSI string for a complete input string 159- `createHighlighter()` returns an incremental highlighter 160- `write()` returns rendered output for the provided chunk 161- `end()` flushes any remaining buffered text 162 163## Token API 164 165The library MUST also expose an ANSI-free token API with **zero runtime dependencies**. 166 167### Token types 168 169```ts 170type InlineSpan = 171 | { type: "text"; content: string } 172 | { type: "bold"; content: string } 173 | { type: "italic"; content: string } 174 | { type: "code"; content: string } 175 | { type: "link"; text: string; url: string }; 176 177type BlockToken = 178 | { type: "heading"; depth: 1 | 2 | 3; spans: InlineSpan[] } 179 | { type: "paragraph"; spans: InlineSpan[] } 180 | { type: "code_block"; lang: string; content: string } 181 | { type: "list_item"; ordered: boolean; index: number; spans: InlineSpan[] } 182 | { type: "blockquote"; spans: InlineSpan[] } 183 | { type: "hr" } 184 | { type: "blank" }; 185``` 186 187### Functions 188 189```ts 190tokenize(input: string): BlockToken[] 191createTokenizer(): TokenHighlighter 192``` 193 194```ts 195interface TokenHighlighter { 196 write(chunk: string | Uint8Array): BlockToken[]; 197 end(): BlockToken[]; 198} 199``` 200 201Behavior: 202 203- `tokenize()` tokenizes a complete Markdown string into block tokens 204- `createTokenizer()` returns an incremental tokenizer for streaming use 205- `write()` returns completed block tokens for the provided chunk 206- `end()` flushes any remaining buffered text and unclosed constructs 207- Streaming `write()` emits completed block tokens immediately; only the current incomplete line is buffered 208- Unclosed fenced code blocks emit as `code_block` on `end()` 209- Unclosed inline formatting falls back to plain `text` spans 210- Inline code has priority over other inline formatting 211 212## CLI 213 214The CLI command is: 215 216```text 217yoctomarkdown [options] [file] 218``` 219 220If `file` is provided, the CLI reads that file. 221Otherwise, it reads from stdin. 222 223Supported options: 224 225- `-t, --theme <name>` 226- `-w, --wrap <n|auto|0>` 227- `-h, --help` 228 229The CLI MUST: 230 231- write rendered output to stdout 232- write diagnostics to stderr 233- exit with status `0` on success 234- exit with non-zero status on input or argument errors 235 236## Non-Goals 237 238- full CommonMark compliance 239- GFM extensions such as tables, task lists, or strikethrough 240- HTML rendering 241- syntax highlighting inside code blocks 242- AST generation