featherdown 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,8 +1,30 @@
1
1
  # featherdown
2
2
 
3
- `featherdown` is a TypeScript package for converting Markdown into sanitized HTML for publishing workflows.
3
+ **featherdown** is an ESM-first Markdown publishing engine for **Node, browsers, and Deno**.
4
4
 
5
- It provides a browser-safe default entry and a separate Node-only Mermaid subpath.
5
+ It turns Markdown into sanitized HTML with a production-friendly pipeline that includes:
6
+
7
+ - GFM
8
+ - math via KaTeX
9
+ - syntax highlighting
10
+ - heading anchors
11
+ - chart placeholder blocks
12
+ - optional manifest-based image rewriting
13
+ - non-fatal render diagnostics
14
+ - an optional **Node-only Mermaid** entry for static SVG rendering
15
+
16
+ It is built for publishing workflows that want more than raw Markdown parsing, but less complexity than assembling and maintaining a full unified stack by hand.
17
+
18
+ ## Why featherdown?
19
+
20
+ Use `featherdown` when you want:
21
+
22
+ - a ready-to-use Markdown → HTML pipeline
23
+ - a browser-safe default entry
24
+ - explicit sanitization instead of “bring your own sanitizer”
25
+ - publishing-oriented extras like chart placeholders and image rewriting
26
+ - optional diagnostics for content issues that should not crash rendering
27
+ - a separate Node-only Mermaid path instead of bundling Node-specific behavior into the default entry
6
28
 
7
29
  ## Install
8
30
 
@@ -10,7 +32,7 @@ It provides a browser-safe default entry and a separate Node-only Mermaid subpat
10
32
  npm install featherdown
11
33
  ```
12
34
 
13
- JSR (Deno):
35
+ JSR / Deno:
14
36
 
15
37
  ```ts
16
38
  import { renderMarkdownToHtml } from "jsr:@karuifeather/featherdown";
@@ -25,7 +47,7 @@ npm install playwright
25
47
  npx playwright install chromium
26
48
  ```
27
49
 
28
- ## Quick Start (Browser-Safe Default Entry)
50
+ ## Quick Start
29
51
 
30
52
  ```ts
31
53
  import { renderMarkdownToHtml } from "featherdown";
@@ -33,11 +55,47 @@ import { renderMarkdownToHtml } from "featherdown";
33
55
  const html = await renderMarkdownToHtml("## Hello **world**");
34
56
  ```
35
57
 
36
- The default entry does not include Mermaid rendering.
58
+ The default entry is browser-safe and does **not** include Mermaid rendering.
59
+
60
+ ## Which API should I use?
61
+
62
+ | If you need... | Use... |
63
+ | --- | --- |
64
+ | Just sanitized HTML output | `renderMarkdownToHtml` |
65
+ | HTML plus non-fatal warnings | `renderMarkdown` |
66
+ | HTML plus publishing metadata (`toc`, `headings`, excerpt, reading stats) | `renderMarkdownDocument` |
67
+ | Direct unified processor access with featherdown defaults | `createMarkdownProcessor` |
68
+ | A custom unified pipeline with focused helpers | `rehypeChartBlocks`, `rehypeCdnImages` |
69
+ | Mermaid-to-inline-SVG rendering in Node publishing flows | `renderMarkdownToHtmlWithMermaid` from `featherdown/node` |
70
+
71
+ Rule of thumb:
72
+
73
+ - Start with `renderMarkdownToHtml`.
74
+ - Move to `renderMarkdown` when content warnings matter.
75
+ - Move to `renderMarkdownDocument` when you need TOC/sidebar/preview metadata.
76
+ - Use `createMarkdownProcessor` only when you need lower-level unified control.
77
+
78
+ ## Common Use Cases
79
+
80
+ ### Render Markdown to HTML
81
+
82
+ ```ts
83
+ import { renderMarkdownToHtml } from "featherdown";
84
+
85
+ const html = await renderMarkdownToHtml(`
86
+ # Post Title
87
+
88
+ Here is some math: $E = mc^2$
89
+
90
+ | Name | Value |
91
+ | ---- | ----- |
92
+ | A | 1 |
93
+ `);
94
+ ```
37
95
 
38
- ## HTML + Diagnostics
96
+ ### Render HTML with warnings
39
97
 
40
- Use `renderMarkdown` to get both HTML and non-fatal warnings.
98
+ Use `renderMarkdown` when you want HTML plus non-fatal diagnostics.
41
99
 
42
100
  ````ts
43
101
  import { renderMarkdown } from "featherdown";
@@ -50,61 +108,99 @@ console.log(html);
50
108
  console.log(diagnostics);
51
109
  ````
52
110
 
53
- ## Processor Factory Usage
111
+ Diagnostics are intended for developer feedback, not end-user rendering.
54
112
 
55
- Use `createMarkdownProcessor` when you want direct control of processing calls.
113
+ ### Render a docs/blog page bundle
114
+
115
+ Use `renderMarkdownDocument` to produce HTML and page metadata in one pass.
56
116
 
57
117
  ```ts
58
- import { createMarkdownProcessor } from "featherdown";
118
+ import { renderMarkdownDocument } from "featherdown";
59
119
 
60
- const processor = createMarkdownProcessor();
61
- const file = await processor.process("# Hello");
62
- const html = String(file);
120
+ const page = await renderMarkdownDocument(markdown);
121
+
122
+ const html = page.html;
123
+ const sidebarItems = page.headings;
124
+ const legacyToc = page.toc;
125
+ const previewText = page.excerpt;
126
+ const readingMinutes = page.estimatedReadingMinutes;
63
127
  ```
64
128
 
65
- ## Direct Plugin Usage
129
+ ### Render HTML with document metadata
66
130
 
67
- The package exports focused plugins for custom unified pipelines.
131
+ Use `renderMarkdownDocument` when publishing workflows need HTML plus heading metadata, excerpt text, and reading stats from the final browser-safe output.
68
132
 
69
133
  ```ts
70
- import { unified } from "unified";
71
- import remarkParse from "remark-parse";
72
- import remarkRehype from "remark-rehype";
73
- import rehypeStringify from "rehype-stringify";
74
- import { rehypeChartBlocks, rehypeCdnImages } from "featherdown";
134
+ import { renderMarkdownDocument } from "featherdown";
75
135
 
76
- const html = String(
77
- await unified()
78
- .use(remarkParse)
79
- .use(remarkRehype)
80
- .use(rehypeChartBlocks)
81
- .use(rehypeCdnImages, { kind: "post", slug: "hello-world" })
82
- .use(rehypeStringify)
83
- .process(markdown),
84
- );
136
+ const document = await renderMarkdownDocument(`
137
+ # Post Title
138
+
139
+ This first paragraph can be used as preview text.
140
+
141
+ ## Section A
142
+ Body text here.
143
+ `);
144
+
145
+ console.log(document.html);
146
+ console.log(document.toc);
147
+ console.log(document.headings);
148
+ console.log(document.excerpt);
149
+ console.log(document.wordCount, document.estimatedReadingMinutes);
85
150
  ```
86
151
 
87
- ## Image Rewriting Example
152
+ Returned metadata:
153
+
154
+ - `toc`: ordered heading list with `depth`, final `text`, and final `id`
155
+ - `headings`: richer ordered heading metadata with `index`, `depth`, final `text`, final `id`, and `hasCustomId`
156
+ - `excerpt`: first meaningful plain-text content from rendered `p`, `blockquote`, or `li`, or `null`
157
+ - `wordCount`: deterministic plain-text word count from rendered document text
158
+ - `estimatedReadingMinutes`: whole-minute estimate from word count (minimum `1` when text exists, `0` when none)
159
+
160
+ `toc` stays intentionally compact for backwards-compatible navigation use, while `headings` is better for richer sidebars, heading-aware tooling, and workflows that need to detect explicit custom heading ids.
161
+
162
+ The metadata is derived from the same processed document structure that produces the final HTML, so heading ids and text stay aligned with rendered output.
163
+
164
+ Common uses include TOC sidebars, preview cards, and reading-time badges.
165
+
166
+ ### Parse front matter
167
+
168
+ ```ts
169
+ import { parseMarkdownFile } from "featherdown";
170
+
171
+ const result = parseMarkdownFile(`---
172
+ title: Hello
173
+ tags:
174
+ - docs
175
+ ---
176
+
177
+ # Hello world
178
+ `);
179
+
180
+ console.log(result.frontMatter);
181
+ console.log(result.content);
182
+ ```
183
+
184
+ ### Publish styled code blocks (title + ranges + numbers + copy hooks)
88
185
 
89
186
  ```ts
90
187
  import { renderMarkdownToHtml } from "featherdown";
91
188
 
92
- const html = await renderMarkdownToHtml("![Logo](./images/logo.png)", {
93
- kind: "post",
94
- slug: "hello-world",
95
- manifest: {
96
- map: {
97
- "post/hello-world/images/logo.png": {
98
- url: "https://cdn.example.com/blog/hello-world/logo.hash.png",
99
- },
100
- },
101
- },
102
- });
189
+ const markdown = `
190
+ \`\`\`ts title="example.ts" {2} showLineNumbers showCopyButton
191
+ const a = 1;
192
+ const b = 2;
193
+ \`\`\`
194
+ `;
195
+
196
+ const html = await renderMarkdownToHtml(markdown);
103
197
  ```
104
198
 
105
- ## Chart Placeholder Example
199
+ ## Publishing Features
106
200
 
107
- Valid JSON in supported `chart-*` fences becomes a placeholder mount node:
201
+ ### Chart placeholder blocks
202
+
203
+ Supported `chart-*` code fences with valid JSON are transformed into placeholder mount nodes.
108
204
 
109
205
  ````md
110
206
  ```chart-line
@@ -122,9 +218,226 @@ Rendered HTML shape:
122
218
  ></div>
123
219
  ```
124
220
 
125
- This package does not bundle a chart runtime; it only emits mount markup.
221
+ `featherdown` does not bundle a chart runtime. It only emits mount markup that your app can hydrate later.
222
+
223
+ ### Code block titles
224
+
225
+ Fenced code blocks can include a title using `title="..."` metadata.
226
+
227
+ ````md
228
+ ```ts title="example.ts"
229
+ const value = 1;
230
+ ```
231
+ ````
232
+
233
+ Emitted HTML contract:
234
+
235
+ ```html
236
+ <div class="code-block">
237
+ <div class="code-block-title">example.ts</div>
238
+ <pre><code class="hljs language-ts">...</code></pre>
239
+ </div>
240
+ ```
241
+
242
+ Title text is treated as plain text, and styling of `code-block` / `code-block-title` is left to the consuming application.
243
+
244
+ ### Code line highlights
245
+
246
+ Fenced code blocks can mark highlighted lines using brace metadata:
247
+
248
+ - `{2}`
249
+ - `{2,4-5}`
250
+ - `{1-3,6}`
251
+
252
+ Highlighted lines receive `code-line-highlighted` in the rendered code, with minimal line wrappers:
253
+
254
+ ```html
255
+ <pre><code class="hljs language-ts">
256
+ <span class="code-line">...</span>
257
+ <span class="code-line code-line-highlighted">...</span>
258
+ </code></pre>
259
+ ```
260
+
261
+ When a code block also has `title="..."`, title markup and line highlighting compose in the same block. Styling is left to the consuming application.
262
+
263
+ ### Code line numbers
264
+
265
+ Fenced code blocks can opt into line numbers with `showLineNumbers`.
266
+
267
+ ````md
268
+ ```ts showLineNumbers
269
+ const a = 1;
270
+ const b = 2;
271
+ ```
272
+ ````
273
+
274
+ Emitted HTML contract:
275
+
276
+ ```html
277
+ <pre><code class="hljs language-ts code-line-numbered">
278
+ <span class="code-line">
279
+ <span class="code-line-number">1</span>
280
+ ...
281
+ </span>
282
+ <span class="code-line code-line-highlighted">
283
+ <span class="code-line-number">2</span>
284
+ ...
285
+ </span>
286
+ </code></pre>
287
+ ```
288
+
289
+ Line number styling is left to the consuming application. Line numbers compose with both `title="..."` and `{...}` line highlight metadata on the same fenced code block.
290
+
291
+ ### Code copy button markup
292
+
293
+ Fenced code blocks can opt into copy-button markup with `showCopyButton` or `copyButton`.
294
+
295
+ ````md
296
+ ```ts title="example.ts" {2} showLineNumbers showCopyButton
297
+ const a = 1;
298
+ const b = 2;
299
+ ```
300
+ ````
301
+
302
+ Emitted HTML contract:
303
+
304
+ ```html
305
+ <div class="code-block code-block-copyable">
306
+ <div class="code-block-title">example.ts</div>
307
+ <button
308
+ type="button"
309
+ class="code-block-copy-button"
310
+ data-code-copy
311
+ data-code-copy-target="code-copy-target-1"
312
+ >
313
+ Copy
314
+ </button>
315
+ <pre><code data-code-copy-target="code-copy-target-1" class="hljs language-ts code-line-numbered">...</code></pre>
316
+ </div>
317
+ ```
318
+
319
+ Styling and clipboard behavior are left to the consuming application. This package emits only HTML contract hooks and does not include built-in clipboard runtime logic.
320
+
321
+ ### Admonitions / callouts
322
+
323
+ The default browser-safe pipeline supports fenced admonitions using `:::type` with a closing `:::`.
324
+ You can optionally provide a title with bracket syntax: `:::type[Title]`.
325
+
326
+ Supported types:
327
+
328
+ - `note`
329
+ - `tip`
330
+ - `warning`
331
+ - `info`
332
+ - `success`
333
+ - `danger`
334
+ - `error`
335
+ - `caution`
336
+ - `important`
337
+
338
+ Example:
339
+
340
+ ````md
341
+ :::note[Install CSS]
342
+ Remember to install KaTeX CSS.
343
+ :::
344
+ ````
345
+
346
+ Emitted HTML contract:
347
+
348
+ ```html
349
+ <div class="callout callout-note">
350
+ <div class="callout-title">Install CSS</div>
351
+ <p>Remember to install KaTeX CSS.</p>
352
+ </div>
353
+ ```
354
+
355
+ When no custom title is provided, a default title is emitted from the callout type (for example `warning` -> `Warning`).
356
+ Callout body content continues through the normal Markdown pipeline, and styling is left to the consuming application.
357
+
358
+ ### Image rewriting
359
+
360
+ Use manifest-based rewriting for relative Markdown images in publishing workflows.
361
+
362
+ ```ts
363
+ import { renderMarkdownToHtml } from "featherdown";
364
+
365
+ const html = await renderMarkdownToHtml("![Logo](./images/logo.png)", {
366
+ kind: "post",
367
+ slug: "hello-world",
368
+ manifest: {
369
+ map: {
370
+ "post/hello-world/images/logo.png": {
371
+ url: "https://cdn.example.com/blog/hello-world/logo.hash.png",
372
+ },
373
+ },
374
+ },
375
+ });
376
+ ```
377
+
378
+ Relative image rewriting is optional and entirely caller-driven. No CDN logic or fetch behavior is bundled into the package.
379
+
380
+ ## Styling hooks
126
381
 
127
- ## Node-Only Mermaid Subpath
382
+ featherdown emits stable classes/data hooks you can style in your own CSS:
383
+
384
+ - callouts: `callout`, `callout-<type>`, `callout-title`
385
+ - code wrappers/titles: `code-block`, `code-block-title`
386
+ - highlighted lines: `code-line`, `code-line-highlighted`
387
+ - numbered lines: `code-line-numbered`, `code-line-number`
388
+ - copy hooks: `code-block-copyable`, `code-block-copy-button`, `data-code-copy`, `data-code-copy-target`
389
+ - chart placeholders: `chart-mount`
390
+ - markdown images: `markdown-inline-img`
391
+
392
+ These are contract hooks, not a built-in theme system. You own the final visual design.
393
+
394
+ ## Common publishing patterns
395
+
396
+ - **Basic post page**: `renderMarkdownToHtml` + app-level CSS.
397
+ - **Editorial QA**: `renderMarkdown` and surface `diagnostics` in author tooling.
398
+ - **Docs/blog navigation**: `renderMarkdownDocument` and drive sidebars from `headings`.
399
+ - **CDN assets**: pass `kind`, `slug`, and `manifest.map`/`manifest.remote`.
400
+ - **Static Mermaid output**: use `featherdown/node` in a trusted Node build step.
401
+
402
+ ## Advanced Usage
403
+
404
+ ### Create the default processor directly
405
+
406
+ Use `createMarkdownProcessor` when you want direct control over processing calls while keeping featherdown’s default browser-safe pipeline.
407
+
408
+ ```ts
409
+ import { createMarkdownProcessor } from "featherdown";
410
+
411
+ const processor = createMarkdownProcessor();
412
+ const file = await processor.process("# Hello");
413
+ const html = String(file);
414
+ ```
415
+
416
+ ### Use the plugins directly
417
+
418
+ The package also exports focused plugins for custom unified pipelines.
419
+
420
+ ```ts
421
+ import { unified } from "unified";
422
+ import remarkParse from "remark-parse";
423
+ import remarkRehype from "remark-rehype";
424
+ import rehypeStringify from "rehype-stringify";
425
+ import { rehypeChartBlocks, rehypeCdnImages } from "featherdown";
426
+
427
+ const html = String(
428
+ await unified()
429
+ .use(remarkParse)
430
+ .use(remarkRehype)
431
+ .use(rehypeChartBlocks)
432
+ .use(rehypeCdnImages, { kind: "post", slug: "hello-world" })
433
+ .use(rehypeStringify)
434
+ .process(markdown),
435
+ );
436
+ ```
437
+
438
+ ## Node-only Mermaid Rendering
439
+
440
+ For static Mermaid rendering, use the separate Node-only entry:
128
441
 
129
442
  ````ts
130
443
  import { renderMarkdownToHtmlWithMermaid } from "featherdown/node";
@@ -134,8 +447,22 @@ const html = await renderMarkdownToHtmlWithMermaid(
134
447
  );
135
448
  ````
136
449
 
137
- Use this entry in Node publishing environments where Playwright + Mermaid dependencies are acceptable.
138
- The `node` Mermaid subpath is npm-focused and is not part of the JSR export surface.
450
+ Use this entry in Node publishing/build environments where Playwright + Chromium dependencies are acceptable.
451
+
452
+ Behavior contract for Mermaid blocks in this entry:
453
+
454
+ - valid Mermaid fences render to inline sanitized SVG
455
+ - invalid Mermaid fences fall back to a normal rendered code block
456
+ - one Mermaid failure does not stop the rest of the document from rendering
457
+
458
+ The Mermaid subpath is npm-focused and is **not** part of the JSR export surface.
459
+
460
+ ## Runtime boundaries
461
+
462
+ - `featherdown` default entry is browser-safe and Mermaid-free.
463
+ - `featherdown/node` is Node-only and includes Mermaid rendering dependencies.
464
+ - `featherdown/node` requires Playwright Chromium setup in the runtime environment.
465
+ - JSR export surface is default-entry focused; Mermaid entry is npm subpath only.
139
466
 
140
467
  ## CSS / Asset Expectations
141
468
 
@@ -145,9 +472,24 @@ The `node` Mermaid subpath is npm-focused and is not part of the JSR export surf
145
472
 
146
473
  ## Security and Trust Guidance
147
474
 
148
- - Input is sanitized with `rehype-sanitize`; scripts are removed.
149
- - Treat Markdown as untrusted by default unless your ingestion workflow guarantees trusted content.
150
- - Review and test your final HTML integration, including any custom render-time plugins you add.
475
+ - Input is sanitized with `rehype-sanitize`.
476
+ - Script tags are stripped.
477
+ - The default entry is designed to be browser-safe.
478
+ - The Mermaid entry is Node-only and is better suited to trusted or controlled publishing inputs than arbitrary user-generated content.
479
+ - For general-purpose rendering of untrusted content, prefer the default `featherdown` entry.
480
+ - Always review your final HTML integration, especially if you add custom plugins around the built-in pipeline.
481
+
482
+ ## Why not just wire unified yourself?
483
+
484
+ You absolutely can.
485
+
486
+ `featherdown` exists for teams that want:
487
+
488
+ - a production-friendly default pipeline
489
+ - deliberate plugin ordering
490
+ - sanitization already considered
491
+ - publishing-oriented features beyond plain Markdown parsing
492
+ - a clean split between browser-safe rendering and Node-only Mermaid rendering
151
493
 
152
494
  ## Public API
153
495
 
@@ -155,6 +497,7 @@ Default entry (`featherdown`):
155
497
 
156
498
  - `renderMarkdownToHtml`
157
499
  - `renderMarkdown`
500
+ - `renderMarkdownDocument`
158
501
  - `createMarkdownProcessor`
159
502
  - `rehypeChartBlocks`
160
503
  - `rehypeCdnImages`
@@ -178,7 +521,7 @@ Node-only entry (`featherdown/node`):
178
521
 
179
522
  ## Maintainers
180
523
 
181
- CI and publishing are described in [RELEASING.md](./RELEASING.md).
524
+ CI and publishing are documented in [RELEASING.md](./RELEASING.md).
182
525
 
183
526
  ## License
184
527