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 +418 -64
- package/dist/chunk-3D4JFT3A.js +552 -0
- package/dist/chunk-3D4JFT3A.js.map +1 -0
- package/dist/index.d.ts +87 -11
- package/dist/index.js +229 -9
- package/dist/index.js.map +1 -1
- package/dist/node.d.ts +9 -1
- package/dist/node.js +17 -2
- package/dist/node.js.map +1 -1
- package/dist/types-BuSz3Zo6.d.ts +139 -0
- package/package.json +14 -1
- package/dist/chunk-CVZY5VWM.js +0 -243
- package/dist/chunk-CVZY5VWM.js.map +0 -1
- package/dist/types-DlRranpy.d.ts +0 -20
package/README.md
CHANGED
|
@@ -1,8 +1,30 @@
|
|
|
1
1
|
# featherdown
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**featherdown** is an ESM-first Markdown publishing engine for **Node, browsers, and Deno**.
|
|
4
4
|
|
|
5
|
-
It
|
|
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
|
|
50
|
+
## Quick Start
|
|
23
51
|
|
|
24
52
|
```ts
|
|
25
|
-
import { renderMarkdownToHtml } from
|
|
53
|
+
import { renderMarkdownToHtml } from "featherdown";
|
|
26
54
|
|
|
27
|
-
const html = await renderMarkdownToHtml(
|
|
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
|
-
|
|
71
|
+
Rule of thumb:
|
|
33
72
|
|
|
34
|
-
|
|
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 {
|
|
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
|
-
|
|
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
|
-
|
|
129
|
+
### Render HTML with document metadata
|
|
48
130
|
|
|
49
|
-
Use `
|
|
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 {
|
|
134
|
+
import { renderMarkdownDocument } from "featherdown";
|
|
53
135
|
|
|
54
|
-
const
|
|
55
|
-
|
|
56
|
-
|
|
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
|
-
|
|
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
|
-
|
|
164
|
+
Common uses include TOC sidebars, preview cards, and reading-time badges.
|
|
165
|
+
|
|
166
|
+
### Parse front matter
|
|
62
167
|
|
|
63
168
|
```ts
|
|
64
|
-
import {
|
|
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
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
184
|
+
### Publish styled code blocks (title + ranges + numbers + copy hooks)
|
|
82
185
|
|
|
83
186
|
```ts
|
|
84
|
-
import { renderMarkdownToHtml } from
|
|
187
|
+
import { renderMarkdownToHtml } from "featherdown";
|
|
85
188
|
|
|
86
|
-
const
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
-
##
|
|
199
|
+
## Publishing Features
|
|
200
|
+
|
|
201
|
+
### Chart placeholder blocks
|
|
100
202
|
|
|
101
|
-
|
|
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="
|
|
217
|
+
data-chart-data='{"labels":["a"],"datasets":[]}'
|
|
116
218
|
></div>
|
|
117
219
|
```
|
|
118
220
|
|
|
119
|
-
|
|
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
|
-
|
|
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 {
|
|
363
|
+
import { renderMarkdownToHtml } from "featherdown";
|
|
125
364
|
|
|
126
|
-
const html = await
|
|
127
|
-
|
|
365
|
+
const html = await renderMarkdownToHtml("", {
|
|
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
|
-
|
|
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
|
|
142
|
-
-
|
|
143
|
-
-
|
|
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
|
|
164
|
-
|
|
165
|
-
| `npm run build`
|
|
166
|
-
| `npm test`
|
|
167
|
-
| `npm run test:watch`
|
|
168
|
-
| `npm run lint`
|
|
169
|
-
| `npm run typecheck`
|
|
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).
|