xonecas.io
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