featherdown 0.1.1 → 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,6 +32,12 @@ It provides a browser-safe default entry and a separate Node-only Mermaid subpat
10
32
  npm install featherdown
11
33
  ```
12
34
 
35
+ JSR / Deno:
36
+
37
+ ```ts
38
+ import { renderMarkdownToHtml } from "jsr:@karuifeather/featherdown";
39
+ ```
40
+
13
41
  Node.js 18+ is required.
14
42
 
15
43
  If you use Mermaid rendering from `featherdown/node`, install Playwright and Chromium:
@@ -19,86 +47,160 @@ npm install playwright
19
47
  npx playwright install chromium
20
48
  ```
21
49
 
22
- ## Quick Start (Browser-Safe Default Entry)
50
+ ## Quick Start
23
51
 
24
52
  ```ts
25
- import { renderMarkdownToHtml } from 'featherdown';
53
+ import { renderMarkdownToHtml } from "featherdown";
26
54
 
27
- const html = await renderMarkdownToHtml('## Hello **world**');
55
+ const html = await renderMarkdownToHtml("## Hello **world**");
28
56
  ```
29
57
 
30
- 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` |
31
70
 
32
- ## HTML + Diagnostics
71
+ Rule of thumb:
33
72
 
34
- Use `renderMarkdown` to get both HTML and non-fatal warnings.
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
35
81
 
36
82
  ```ts
37
- import { renderMarkdown } from 'featherdown';
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
+ ```
95
+
96
+ ### Render HTML with warnings
97
+
98
+ Use `renderMarkdown` when you want HTML plus non-fatal diagnostics.
99
+
100
+ ````ts
101
+ import { renderMarkdown } from "featherdown";
38
102
 
39
103
  const { html, diagnostics } = await renderMarkdown(
40
- '```chart-line\nnot json\n```',
104
+ "```chart-line\nnot json\n```",
41
105
  );
42
106
 
43
107
  console.log(html);
44
108
  console.log(diagnostics);
109
+ ````
110
+
111
+ Diagnostics are intended for developer feedback, not end-user rendering.
112
+
113
+ ### Render a docs/blog page bundle
114
+
115
+ Use `renderMarkdownDocument` to produce HTML and page metadata in one pass.
116
+
117
+ ```ts
118
+ import { renderMarkdownDocument } from "featherdown";
119
+
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;
45
127
  ```
46
128
 
47
- ## Processor Factory Usage
129
+ ### Render HTML with document metadata
48
130
 
49
- Use `createMarkdownProcessor` when you want direct control of processing calls.
131
+ Use `renderMarkdownDocument` when publishing workflows need HTML plus heading metadata, excerpt text, and reading stats from the final browser-safe output.
50
132
 
51
133
  ```ts
52
- import { createMarkdownProcessor } from 'featherdown';
134
+ import { renderMarkdownDocument } from "featherdown";
53
135
 
54
- const processor = createMarkdownProcessor();
55
- const file = await processor.process('# Hello');
56
- const html = String(file);
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);
57
150
  ```
58
151
 
59
- ## Direct Plugin Usage
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.
60
163
 
61
- The package exports focused plugins for custom unified pipelines.
164
+ Common uses include TOC sidebars, preview cards, and reading-time badges.
165
+
166
+ ### Parse front matter
62
167
 
63
168
  ```ts
64
- import { unified } from 'unified';
65
- import remarkParse from 'remark-parse';
66
- import remarkRehype from 'remark-rehype';
67
- import rehypeStringify from 'rehype-stringify';
68
- import { rehypeChartBlocks, rehypeCdnImages } from 'featherdown';
169
+ import { parseMarkdownFile } from "featherdown";
69
170
 
70
- const html = String(
71
- await unified()
72
- .use(remarkParse)
73
- .use(remarkRehype)
74
- .use(rehypeChartBlocks)
75
- .use(rehypeCdnImages, { kind: 'post', slug: 'hello-world' })
76
- .use(rehypeStringify)
77
- .process(markdown),
78
- );
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);
79
182
  ```
80
183
 
81
- ## Image Rewriting Example
184
+ ### Publish styled code blocks (title + ranges + numbers + copy hooks)
82
185
 
83
186
  ```ts
84
- import { renderMarkdownToHtml } from 'featherdown';
187
+ import { renderMarkdownToHtml } from "featherdown";
85
188
 
86
- const html = await renderMarkdownToHtml('![Logo](./images/logo.png)', {
87
- kind: 'post',
88
- slug: 'hello-world',
89
- manifest: {
90
- map: {
91
- 'post/hello-world/images/logo.png': {
92
- url: 'https://cdn.example.com/blog/hello-world/logo.hash.png',
93
- },
94
- },
95
- },
96
- });
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);
97
197
  ```
98
198
 
99
- ## Chart Placeholder Example
199
+ ## Publishing Features
200
+
201
+ ### Chart placeholder blocks
100
202
 
101
- Valid JSON in supported `chart-*` fences becomes a placeholder mount node:
203
+ Supported `chart-*` code fences with valid JSON are transformed into placeholder mount nodes.
102
204
 
103
205
  ````md
104
206
  ```chart-line
@@ -112,23 +214,255 @@ Rendered HTML shape:
112
214
  <div
113
215
  class="chart-mount"
114
216
  data-chart="line"
115
- data-chart-data="{&quot;labels&quot;:[&quot;a&quot;],&quot;datasets&quot;:[]}"
217
+ data-chart-data='{"labels":["a"],"datasets":[]}'
116
218
  ></div>
117
219
  ```
118
220
 
119
- 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.
120
290
 
121
- ## Node-Only Mermaid Subpath
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.
122
361
 
123
362
  ```ts
124
- import { renderMarkdownToHtmlWithMermaid } from 'featherdown/node';
363
+ import { renderMarkdownToHtml } from "featherdown";
125
364
 
126
- const html = await renderMarkdownToHtmlWithMermaid(
127
- '```mermaid\ngraph TD; A-->B;\n```',
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
381
+
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),
128
435
  );
129
436
  ```
130
437
 
131
- Use this entry in Node publishing environments where Playwright + Mermaid dependencies are acceptable.
438
+ ## Node-only Mermaid Rendering
439
+
440
+ For static Mermaid rendering, use the separate Node-only entry:
441
+
442
+ ````ts
443
+ import { renderMarkdownToHtmlWithMermaid } from "featherdown/node";
444
+
445
+ const html = await renderMarkdownToHtmlWithMermaid(
446
+ "```mermaid\ngraph TD; A-->B;\n```",
447
+ );
448
+ ````
449
+
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.
132
466
 
133
467
  ## CSS / Asset Expectations
134
468
 
@@ -138,9 +472,24 @@ Use this entry in Node publishing environments where Playwright + Mermaid depend
138
472
 
139
473
  ## Security and Trust Guidance
140
474
 
141
- - Input is sanitized with `rehype-sanitize`; scripts are removed.
142
- - Treat Markdown as untrusted by default unless your ingestion workflow guarantees trusted content.
143
- - 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
144
493
 
145
494
  ## Public API
146
495
 
@@ -148,6 +497,7 @@ Default entry (`featherdown`):
148
497
 
149
498
  - `renderMarkdownToHtml`
150
499
  - `renderMarkdown`
500
+ - `renderMarkdownDocument`
151
501
  - `createMarkdownProcessor`
152
502
  - `rehypeChartBlocks`
153
503
  - `rehypeCdnImages`
@@ -160,15 +510,19 @@ Node-only entry (`featherdown/node`):
160
510
 
161
511
  ## Scripts
162
512
 
163
- | Script | Description |
164
- |---|---|
165
- | `npm run build` | Build ESM artifacts in `dist/` |
166
- | `npm test` | Run Vitest once |
167
- | `npm run test:watch` | Run Vitest in watch mode |
168
- | `npm run lint` | Run ESLint |
169
- | `npm run typecheck` | Run TypeScript checks |
513
+ | Script | Description |
514
+ | ---------------------- | --------------------------------- |
515
+ | `npm run build` | Build ESM artifacts in `dist/` |
516
+ | `npm test` | Run Vitest once |
517
+ | `npm run test:watch` | Run Vitest in watch mode |
518
+ | `npm run lint` | Run ESLint |
519
+ | `npm run typecheck` | Run TypeScript checks |
170
520
  | `npm run test:exports` | Build and run export smoke checks |
171
521
 
522
+ ## Maintainers
523
+
524
+ CI and publishing are documented in [RELEASING.md](./RELEASING.md).
525
+
172
526
  ## License
173
527
 
174
528
  MIT. See [LICENSE](./LICENSE).