xonecas.io
6533
Yo

yoctomarkdown / files

yoctomarkdown / README.md

2.6 KB
1# yoctomarkdown
2
3A small, fast, Bun-native Markdown highlighter for terminal output.
4
5`yoctomarkdown` reads Markdown and writes ANSI-colored text to stdout or returns it as a string. It focuses on simple, fast, incremental rendering for CLI and programmatic use, supporting a practical subset of Markdown specifically for terminal display.
6
7## Features
8
9- **Incremental processing**: Stream chunks of Markdown without buffering the entire document.
10- **Terminal optimized**: Styles headings, code blocks, lists, and more using `yoctocolors`.
11- **Flexible**: Use it as a library (`highlightSync`, `createHighlighter`) or as a CLI tool.
12- **Fast**: Built for the Bun runtime.
13
14## Installation
15
16[npm package](https://www.npmjs.com/package/yoctomarkdown)
17
18```bash
19bun add yoctomarkdown
20```
21
22## Usage
23
24### CLI
25
26Run via the command line:
27
28```bash
29# Read from a file
30yoctomarkdown README.md
31
32# Read from stdin
33cat README.md | yoctomarkdown
34```
35
36**Options:**
37
38- `-t, --theme <name>`: Theme to use (`16`, `256`, `truecolor`, `minimal`, `none`). Defaults to `16`.
39- `-w, --wrap <n|auto|0>`: Word wrapping length. Defaults to `auto` (terminal width).
40- `-h, --help`: Show help.
41
42### Library API
43
44You can use `yoctomarkdown` programmatically in two ways: synchronously for complete strings, or incrementally via the highlighter.
45
46#### Synchronous
47
48```typescript
49import { highlightSync } from "yoctomarkdown";
50
51const markdown = "# Hello World\n\nThis is **bold** text.";
52const output = highlightSync(markdown, { theme: "truecolor" });
53console.log(output);
54```
55
56#### Streaming / Incremental
57
58```typescript
59import { createHighlighter } from "yoctomarkdown";
60
61const highlighter = createHighlighter({ theme: "16" });
62
63process.stdout.write(highlighter.write("# Chunk 1\n"));
64process.stdout.write(highlighter.write("Some *italic* text in Chunk 2.\n"));
65process.stdout.write(highlighter.end());
66```
67
68## Options
69
70```typescript
71interface Options {
72  theme?: "16" | "256" | "truecolor" | "minimal" | "none" | Theme; // default: "16"
73  tabWidth?: number; // default: 2
74  wordWrap?: number | "auto" | 0; // default: "auto"
75  yieldEvery?: number; // default: 1000
76}
77```
78
79## Supported Markdown
80
81- Headings (`#`, `##`, `###`)
82- Bold (`**text**`) and Italic (`*text*`)
83- Inline code (` \`code\` `) and Fenced code blocks (` ``` `)
84- Links (`[text](url)`)
85- Lists (`-`, `*`, `1.`)
86- Blockquotes (`>`)
87- Horizontal rules (`---`)
88
89Unsupported Markdown elements are preserved as plain text.
90
91## Scripts
92
93To contribute or develop locally, the following commands are available:
94
95- `bun run check`: Runs formatting, linting, typechecking, and duplication checks.
96- `bun run format`: Formats code using Prettier.
97- `bun test`: Runs tests.