featherdown 0.1.2 → 0.3.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,10 @@
1
1
  # featherdown
2
2
 
3
- `featherdown` is a TypeScript package for converting Markdown into sanitized HTML for publishing workflows.
3
+ **featherdown** is a publishing-focused Markdown engine for apps, blogs, docs, and product surfaces that want **sanitized HTML**, **publishing metadata**, **diagnostics**, **code and math support**, and **asset hints**—without hand-wiring a full [unified](https://github.com/unifiedjs/unified) pipeline.
4
4
 
5
- It provides a browser-safe default entry and a separate Node-only Mermaid subpath.
5
+ It is **not** a static site generator and does not ship client runtimes for charts, copy-to-clipboard behavior, or Mermaid in the browser. It produces HTML contracts and metadata your app can integrate.
6
+
7
+ The default npm entry is **browser-safe**. Optional **Node-only** Mermaid (inline SVG) lives behind `featherdown/node`.
6
8
 
7
9
  ## Install
8
10
 
@@ -10,175 +12,448 @@ It provides a browser-safe default entry and a separate Node-only Mermaid subpat
10
12
  npm install featherdown
11
13
  ```
12
14
 
13
- JSR (Deno):
15
+ Node.js **18+** is required.
16
+
17
+ ### JSR / Deno
18
+
19
+ You can import the library from JSR (see [@karuifeather/featherdown](https://jsr.io/@karuifeather/featherdown)). **npm** publishes **CSS subpath exports** (`featherdown/styles.css`, `featherdown/styles/base.css`, and the other `featherdown/styles/*` entries in `package.json`). **Deno/JSR** (`deno.json` exports) does **not** mirror those CSS paths today—**CSS parity for JSR is deferred**; treat stylesheet wiring as environment-specific. **CSS packaging and `@import` resolution for JSR/Deno consumers are not treated as equivalent to npm bundler workflows.** Prefer npm (or a bundler) when you want the documented CSS entry points without extra setup.
20
+
21
+ ## Quick start
14
22
 
15
23
  ```ts
16
- import { renderMarkdownToHtml } from "jsr:@karuifeather/featherdown";
24
+ import { Featherdown } from "featherdown";
25
+ import "featherdown/styles.css";
26
+
27
+ const featherdown = new Featherdown();
28
+
29
+ const result = await featherdown.parse("# Hello");
30
+
31
+ console.log(result.html);
17
32
  ```
18
33
 
19
- Node.js 18+ is required.
34
+ The default entry is browser-safe and does **not** include Mermaid rendering.
20
35
 
21
- If you use Mermaid rendering from `featherdown/node`, install Playwright and Chromium:
36
+ ## Rendering Markdown
22
37
 
23
- ```bash
24
- npm install playwright
25
- npx playwright install chromium
38
+ Use the **`Featherdown`** class as the primary API. Constructor options set defaults; each call to **`parse(markdown, parseOptions?)`** can override them (with a shallow merge and one-level merge for nested groups like `code` and `publishing`).
39
+
40
+ ```ts
41
+ const featherdown = new Featherdown({
42
+ frontmatter: "auto",
43
+ math: true,
44
+ code: true,
45
+ diagnostics: "warn",
46
+ });
47
+
48
+ const result = await featherdown.parse(markdown);
26
49
  ```
27
50
 
28
- ## Quick Start (Browser-Safe Default Entry)
51
+ ### Image manifest example
29
52
 
30
53
  ```ts
31
- import { renderMarkdownToHtml } from "featherdown";
54
+ const featherdown = new Featherdown({
55
+ kind: "post",
56
+ slug: "hello-world",
57
+ manifest: {
58
+ map: {
59
+ "post/hello-world/images/logo.png": { url: "https://cdn.example.com/logo.png" },
60
+ },
61
+ },
62
+ });
32
63
 
33
- const html = await renderMarkdownToHtml("## Hello **world**");
64
+ const result = await featherdown.parse(markdown);
34
65
  ```
35
66
 
36
- The default entry does not include Mermaid rendering.
67
+ ## Result object
37
68
 
38
- ## HTML + Diagnostics
69
+ `Featherdown.parse()` resolves to a **`FeatherdownResult`**. Commonly used fields:
39
70
 
40
- Use `renderMarkdown` to get both HTML and non-fatal warnings.
71
+ | Field | Meaning |
72
+ | --- | --- |
73
+ | **`html`** | Sanitized HTML string. |
74
+ | **`body`** | Markdown body after front matter is stripped when front matter parsing is enabled and a valid block exists; otherwise the full input string. |
75
+ | **`frontmatter`** | Parsed YAML object, or `{}` when absent or when front matter parsing is disabled. |
76
+ | **`metadata`** | Normalized subset of common publishing fields (`title`, `description`, `tags`, etc.) derived from front matter. |
77
+ | **`toc`** | Compact heading list for navigation (`depth`, `text`, `id`). |
78
+ | **`headings`** | Richer heading metadata in document order (includes `hasCustomId`). |
79
+ | **`excerpt`** | First meaningful plain-text excerpt from rendered flow content, or `null` when disabled or unavailable. |
80
+ | **`wordCount`** / **`estimatedReadingMinutes`** | Derived from the rendered document text (subject to `publishing` options). |
81
+ | **`stats`** | Mirrors `wordCount` and reading time for convenience. |
82
+ | **`diagnostics`** | Non-fatal warnings (for example invalid chart JSON or manifest misses). |
83
+ | **`assets`** | Hints such as **`assets.styles`** (selective package CSS paths) and **`assets.features`** (`math`, `code`, `charts`, `mermaid`). |
41
84
 
42
- ````ts
43
- import { renderMarkdown } from "featherdown";
85
+ `assets.styles` lists **selective** style paths (for example `featherdown/styles/base.css`), not the all-in `featherdown/styles.css` aggregate.
44
86
 
45
- const { html, diagnostics } = await renderMarkdown(
46
- "```chart-line\nnot json\n```",
47
- );
87
+ ## Styles
48
88
 
49
- console.log(html);
50
- console.log(diagnostics);
51
- ````
89
+ Official styles target the **`featherdown-content`** wrapper class and related HTML contracts.
52
90
 
53
- ## Processor Factory Usage
91
+ ### All-in (recommended starting point)
54
92
 
55
- Use `createMarkdownProcessor` when you want direct control of processing calls.
93
+ These entry points are intended for **npm / bundler** workflows where the toolchain resolves package paths and nested `@import`s.
56
94
 
57
95
  ```ts
58
- import { createMarkdownProcessor } from "featherdown";
96
+ import "featherdown/styles.css";
97
+ ```
98
+
99
+ This aggregates base, KaTeX, code, and highlight layers. It is the simplest path when you want the full default look.
100
+
101
+ ### Selective imports
102
+
103
+ For smaller CSS payloads, import only what you need:
59
104
 
60
- const processor = createMarkdownProcessor();
61
- const file = await processor.process("# Hello");
62
- const html = String(file);
105
+ ```ts
106
+ import "featherdown/styles/base.css";
107
+ import "featherdown/styles/katex.css"; // when math is enabled
108
+ import "featherdown/styles/code.css"; // when code blocks / shell chrome are used
109
+ import "featherdown/styles/highlight.css"; // only when syntax highlighting is enabled
63
110
  ```
64
111
 
65
- ## Direct Plugin Usage
112
+ - **`base.css`** — Prose/layout and structural contracts for rendered content.
113
+ - **`katex.css`** — Bundler-oriented entry that pulls in KaTeX’s distribution CSS for math output.
114
+ - **`code.css`** — Featherdown code-block shell / chrome (titles, line layout hooks, etc.).
115
+ - **`highlight.css`** — Default highlight.js theme CSS; **include this only when syntax highlighting is enabled** (`code` with default highlighting, or equivalent).
116
+
117
+ Do **not** assume raw `<link href="node_modules/.../featherdown/styles.css">` without a bundler will resolve nested `@import`s the same way a bundler does.
66
118
 
67
- The package exports focused plugins for custom unified pipelines.
119
+ ### Custom themes
120
+
121
+ You can start from Featherdown's baseline styles and override them:
68
122
 
69
123
  ```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";
124
+ import "featherdown/styles/base.css";
125
+ import "./markdown-theme.css";
126
+ import "./code-theme.css";
127
+ ```
75
128
 
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
- );
129
+ Or skip `base.css` and fully own the rendered Markdown styles in your app.
130
+
131
+ When code highlighting is enabled, rendered code uses highlight.js-style `hljs` token classes, so custom code themes can target classes such as `.hljs-keyword`, `.hljs-string`, and `.hljs-comment`.
132
+
133
+ ### Asset hints
134
+
135
+ ```ts
136
+ const result = await featherdown.parse(markdown);
137
+ console.log(result.assets.styles);
85
138
  ```
86
139
 
87
- ## Image Rewriting Example
140
+ Use this in SSR or static generators to decide which stylesheets to emit alongside HTML.
141
+
142
+ ## Options
143
+
144
+ These options are wired end-to-end today:
88
145
 
89
146
  ```ts
90
- import { renderMarkdownToHtml } from "featherdown";
147
+ const featherdown = new Featherdown({
148
+ frontmatter: "auto",
149
+ math: true,
150
+ code: true,
151
+ sanitize: true,
152
+ diagnostics: true,
153
+ charts: true,
154
+ headings: true,
155
+ publishing: true,
156
+ });
157
+ ```
91
158
 
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
- },
159
+ Object forms for nested groups:
160
+
161
+ ```ts
162
+ const featherdown = new Featherdown({
163
+ code: {
164
+ enabled: true,
165
+ highlighting: true,
166
+ },
167
+ publishing: {
168
+ excerpt: true,
169
+ wordCount: true,
170
+ readingTime: true,
101
171
  },
102
172
  });
103
173
  ```
104
174
 
105
- ## Chart Placeholder Example
175
+ - **`math`** — Toggle KaTeX HTML output for `$…$` / `$$…$$`.
176
+ - **`code`** — Toggle code pipeline features; **`highlighting`** controls whether highlight.js classes and **`highlight.css`** are relevant.
177
+ - **`frontmatter`** — `false`, `true`, or `"auto"`; controls whether leading YAML front matter is parsed and stripped from `body`.
178
+ - **`sanitize`** — When enabled, output passes through `rehype-sanitize` with the package schema.
179
+ - **`diagnostics`** — Controls whether warnings appear on the result and whether strict mode fails the parse.
180
+ - **`false`** — `result.diagnostics` is always `[]` (issues may still be detected internally).
181
+ - **`true`** or **`"warn"`** — Non-fatal diagnostics are returned on `result.diagnostics`; the parse does not throw.
182
+ - **`"strict"`** — Same collection as warn; if any diagnostic exists after rendering, the parse throws **`FeatherdownDiagnosticsError`** with **`error.diagnostics`** and optional **`error.result`** (full `FeatherdownResult`, including `html`). Use `instanceof FeatherdownDiagnosticsError` in callers that need to branch.
183
+
184
+ ```ts
185
+ import { Featherdown, FeatherdownDiagnosticsError } from "featherdown";
106
186
 
107
- Valid JSON in supported `chart-*` fences becomes a placeholder mount node:
187
+ const featherdown = new Featherdown({
188
+ diagnostics: "warn",
189
+ });
108
190
 
109
- ````md
110
- ```chart-line
111
- {"labels":["a"],"datasets":[]}
191
+ const strict = new Featherdown({
192
+ diagnostics: "strict",
193
+ });
194
+
195
+ try {
196
+ await strict.parse(markdown);
197
+ } catch (e) {
198
+ if (e instanceof FeatherdownDiagnosticsError) {
199
+ console.error(e.diagnostics);
200
+ }
201
+ }
112
202
  ```
113
- ````
203
+ - **`charts`** — When enabled, valid `chart-*` fences become mount placeholders; invalid JSON surfaces diagnostics when diagnostics are enabled.
204
+ - **`headings`** — Controls **`result.headings`** and **`result.toc`** (metadata extracted after render). Heading markup in **`html`** is unchanged; this option gates the arrays on the result.
205
+ - **`false`** — **`result.headings`** and **`result.toc`** are both empty arrays.
206
+ - **`true`** — Default heading metadata: both arrays are populated when rendered headings have ids.
207
+ - **Object** — Shape matches **`FeatherdownHeadingOptions`**: optional **`toc`**. When **`toc`** is **`false`**, **`result.toc`** is empty while **`result.headings`** can still be filled. Optional **`slugs`** and **`anchors`** are part of the public type and merge like other nested options; they do not toggle the Markdown processor in this release.
208
+ - **`publishing`** — Gates excerpt, word count, and reading-time fields on the result.
209
+
210
+ **`kind`**, **`slug`**, and **`manifest`** (local `map` and optional `remote`) drive manifest-based image URL rewriting—the same shape supported historically on render helpers.
114
211
 
115
- Rendered HTML shape:
212
+ Avoid treating every nested field on `FeatherdownOptions` as a global behavioral switch unless documented below (for example line numbers and copy UI remain **per-fence** in Markdown).
116
213
 
117
- ```html
118
- <div
119
- class="chart-mount"
120
- data-chart="line"
121
- data-chart-data='{"labels":["a"],"datasets":[]}'
122
- ></div>
214
+ ## Front matter
215
+
216
+ Publishing-style front matter is **opt in**. The default constructor does **not** strip YAML; pass **`frontmatter: "auto"`** (or `true`) when you want leading `---` YAML parsed and removed from the body string.
217
+
218
+ ```ts
219
+ const featherdown = new Featherdown({
220
+ frontmatter: "auto",
221
+ });
222
+
223
+ const result = await featherdown.parse(`---
224
+ title: Hello World
225
+ tags:
226
+ - docs
227
+ ---
228
+
229
+ # Hello`);
123
230
  ```
124
231
 
125
- This package does not bundle a chart runtime; it only emits mount markup.
232
+ Then:
233
+
234
+ - `result.frontmatter.title`, `result.metadata.title`
235
+ - `result.body` — Markdown after the front matter block
236
+ - `result.html` — Rendered from `body` only
237
+
238
+ **Lenient behavior:** invalid or non-mapping YAML does not throw; the raw document is treated as body content with empty `frontmatter` / `metadata` where applicable.
239
+
240
+ **Strict legacy utility:** `parseMarkdownFile()` still throws on invalid YAML and returns **`frontMatter`** / **`content`**. Use it only when you need that contract; otherwise prefer `Featherdown` with `frontmatter: "auto"`.
126
241
 
127
- ## Node-Only Mermaid Subpath
242
+ ## Code blocks
128
243
 
129
- ````ts
130
- import { renderMarkdownToHtmlWithMermaid } from "featherdown/node";
244
+ - **Fenced code** renders as sanitized `<pre><code>` with highlight.js classes when highlighting is on.
245
+ - **Titles:** ` ```ts title="example.ts" ` — emits `code-block` / `code-block-title` markup.
246
+ - **Line highlights:** ` ```ts {2,4-5} ` — `code-line` / `code-line-highlighted` wrappers.
247
+ - **Line numbers:** ` ```ts showLineNumbers ` — `code-line-numbered` and per-line number spans (per fence).
248
+ - **Copy UI hooks:** `showCopyButton` / `copyButton` on the fence emit button markup and `data-*` attributes for your app to wire up. **The package does not ship clipboard JavaScript.**
131
249
 
132
- const html = await renderMarkdownToHtmlWithMermaid(
133
- "```mermaid\ngraph TD; A-->B;\n```",
134
- );
135
- ````
250
+ Styling for these contracts comes from **`code.css`** and **`highlight.css`** (when highlighting is enabled).
136
251
 
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.
252
+ ## Math
139
253
 
140
- ## CSS / Asset Expectations
254
+ Enable math on the instance or per parse:
255
+
256
+ ```ts
257
+ const featherdown = new Featherdown({
258
+ math: true,
259
+ });
260
+ ```
141
261
 
142
- - KaTeX CSS is required for correct math styling.
143
- - Syntax highlighting output includes highlight.js classes; include matching styles in your app.
144
- - Mermaid rendering from `featherdown/node` depends on Playwright Chromium availability.
262
+ Ensure KaTeX styles are loaded (all-in `featherdown/styles.css`, or `featherdown/styles/katex.css`). The public option name is **`math`**; KaTeX is used internally for HTML output.
145
263
 
146
- ## Security and Trust Guidance
264
+ ## Charts, callouts, and publishing features
147
265
 
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.
266
+ ### Chart placeholders
151
267
 
152
- ## Public API
268
+ Valid `chart-*` fenced JSON becomes a **`chart-mount`** placeholder with `data-chart` and `data-chart-data`. The package does **not** bundle a chart runtime—your app hydrates or renders charts.
153
269
 
154
- Default entry (`featherdown`):
270
+ ### Callouts (admonitions)
155
271
 
156
- - `renderMarkdownToHtml`
157
- - `renderMarkdown`
158
- - `createMarkdownProcessor`
159
- - `rehypeChartBlocks`
160
- - `rehypeCdnImages`
161
- - `parseMarkdownFile`
162
- - `libraryId`
272
+ `:::note`, `:::warning`, `:::tip`, etc. (with optional `:::type[Title]`) render to **`callout`** / **`callout-<type>`** structures. Body markdown is processed normally.
163
273
 
164
- Node-only entry (`featherdown/node`):
274
+ ### Images
165
275
 
166
- - `renderMarkdownToHtmlWithMermaid`
276
+ Optional **`manifest`** + **`kind`** + **`slug`** rewrite relative `![alt](./path)` sources using deterministic keys. No CDN fetching is built in.
277
+
278
+ ### TOC, excerpt, counts
279
+
280
+ `toc`, `headings`, `excerpt`, `wordCount`, and `estimatedReadingMinutes` come from the **same** render pass as `html`, gated by **`headings`** and **`publishing`** options.
281
+
282
+ ## Node usage
283
+
284
+ Import **`Featherdown` from `featherdown/node`** for filesystem helpers and optional Mermaid.
285
+
286
+ ```ts
287
+ import { Featherdown } from "featherdown/node";
288
+
289
+ const featherdown = new Featherdown({
290
+ frontmatter: "auto",
291
+ });
292
+
293
+ const result = await featherdown.parseFile("./posts/hello.md");
294
+ ```
295
+
296
+ - **`parseFile(path)`** reads UTF-8 and returns the same **`FeatherdownResult`** as **`parse(markdown)`** for the same file contents and options.
297
+
298
+ ## Mermaid (Node only)
299
+
300
+ Inline SVG Mermaid is available **only** through the Node entry, with **`mermaid: { render: "svg" }`**. There is **no** placeholder-only mode documented today.
301
+
302
+ ```ts
303
+ import { Featherdown } from "featherdown/node";
304
+
305
+ const featherdown = new Featherdown({
306
+ mermaid: {
307
+ render: "svg",
308
+ },
309
+ });
310
+
311
+ const result = await featherdown.parse(markdown);
312
+ ```
313
+
314
+ - Uses **`rehype-mermaid`** and may require the **optional Playwright / Chromium** peer setup (`playwright` + `npx playwright install chromium`). Failures can be **environment-sensitive** in CI.
315
+ - Valid diagrams become inline **SVG** in `html`; **`result.assets.features.mermaid`** is **`true`** when this path is active.
316
+ - The Node Mermaid pipeline uses a **final SVG-aware sanitize** step and does **not** match every rehype plugin order detail of the default browser pipeline—expect rare edge differences for exotic inputs.
317
+
318
+ The default **`featherdown`** entry remains Mermaid-free for bundle safety.
319
+
320
+ ## Advanced and compatibility APIs
321
+
322
+ ### `featherdown/advanced`
323
+
324
+ The advanced subpath is for **existing low-level unified integrations**. Most applications should use **`Featherdown`**. The subpath exists for **existing unified pipelines** and low-level compatibility:
325
+
326
+ ```ts
327
+ import {
328
+ createMarkdownProcessor,
329
+ rehypeChartBlocks,
330
+ rehypeCdnImages,
331
+ } from "featherdown/advanced";
332
+ ```
333
+
334
+ The same symbols remain re-exported from the **root** package for backward compatibility; prefer **`Featherdown`** for normal Markdown rendering.
335
+
336
+ ### Legacy function exports
337
+
338
+ Older helpers (`renderMarkdownToHtml`, `renderMarkdown`, `renderMarkdownDocument`, `parseMarkdownFile`, `createMarkdownProcessor`, …) remain exported and marked **`@deprecated`**. They take **`RenderMarkdownOptions`**, not the full **`FeatherdownOptions`** surface (for example **`math`**, **`code`**, **`charts`**, **`frontmatter`**, and **`diagnostics: "strict"`** are **`Featherdown`** features). Prefer **`new Featherdown().parse()`** for new code.
339
+
340
+ ## Migration from legacy helpers
341
+
342
+ Legacy helpers remain available for compatibility, but new code should use **`Featherdown`**.
343
+
344
+ For default rendering behavior (what the legacy helpers covered under **`RenderMarkdownOptions`**), the closest migration is:
345
+
346
+ ```ts
347
+ // Before
348
+ const html = await renderMarkdownToHtml(markdown);
349
+
350
+ // After
351
+ const { html } = await new Featherdown().parse(markdown);
352
+ ```
353
+
354
+ > **Migration note:** The legacy helpers are kept for compatibility and use the older **`RenderMarkdownOptions`** surface. They are not a full alias for **`FeatherdownOptions`**. For feature gates such as **`math`**, **`code`**, **`charts`**, **`frontmatter`**, and **`diagnostics: "strict"`**, use the **`Featherdown`** class.
355
+
356
+ | Legacy | Prefer |
357
+ | --- | --- |
358
+ | `renderMarkdownToHtml(md, opts)` | `(await new Featherdown().parse(md)).html` — legacy **`opts`** only apply the older options shape; pass **`FeatherdownOptions`** on **`Featherdown`** when you need feature gates |
359
+ | `renderMarkdown(md, opts)` | `await new Featherdown().parse(md)` — use **`r.html`** and **`r.diagnostics`**; same **`RenderMarkdownOptions`** limitation as above |
360
+ | `renderMarkdownDocument(md, opts)` | `await new Featherdown().parse(md)` for the default document pipeline when **`opts`** are legacy **`RenderMarkdownOptions`**. The **`Featherdown`** result adds **`body`**, **`frontmatter`**, **`assets`**, and related fields—configure **`Featherdown`** directly if you need **`FeatherdownOptions`** (not understood by the helper) |
361
+ | `parseMarkdownFile(md)` | `new Featherdown({ frontmatter: "auto" }).parse(md)` returns **`frontmatter`**, **`metadata`**, **`body`**, and **`html`** in one result. Keep **`parseMarkdownFile`** only when you need its strict **`{ frontMatter, content }`** contract |
362
+ | `renderMarkdownToHtmlWithMermaid(md, opts)` (Node) | `new Featherdown({ mermaid: { render: "svg" } }).parse(md)` then read **`html`** from **`featherdown/node`** — add **`kind`**, **`manifest`**, and other options in the same object as needed; **do not spread** an options object that might already define **`mermaid`** (merge carefully or use a dedicated instance). Legacy **`opts`** remain **`RenderMarkdownOptions`**-shaped |
363
+ | `createMarkdownProcessor(opts)` | **`Featherdown`** for normal use; **`featherdown/advanced`** only for custom unified graphs |
364
+
365
+ **Strict diagnostics:** **`diagnostics: "strict"`** exists only on **`Featherdown`**; legacy render helpers do not use it.
366
+
367
+ ## Styling reference (HTML contracts)
368
+
369
+ Rendered output uses stable classes including:
370
+
371
+ - **Article surface:** wrap content in **`featherdown-content`** (see shipped CSS).
372
+ - **Callouts:** `callout`, `callout-<type>`, `callout-title`
373
+ - **Code:** `code-block`, `code-block-title`, `code-line`, `code-line-highlighted`, `code-line-numbered`, `code-line-number`, `code-block-copyable`, `code-block-copy-button`
374
+ - **Charts:** `chart-mount`
375
+ - **Images:** `markdown-inline-img`
376
+
377
+ ## Security and trust
378
+
379
+ - Input is sanitized (`rehype-sanitize`); scripts are stripped in the default pipeline.
380
+ - Prefer the **default** entry for untrusted user content.
381
+ - The **Node Mermaid** path is better suited to **trusted** publishing inputs.
382
+
383
+ ## Runtime boundaries
384
+
385
+ | Entry | Role |
386
+ | --- | --- |
387
+ | **`featherdown`** | Browser-safe; no Mermaid / Playwright in the default bundle. |
388
+ | **`featherdown/node`** | Node **`Featherdown`**, optional Mermaid SVG, **`parseFile`**. |
389
+ | **`featherdown/advanced`** | Processor + rehype plugins for unified integrations. |
390
+
391
+ Mermaid is **npm subpath–oriented**; JSR usage focuses on the default library surface.
392
+
393
+ ### Client-side Mermaid previews
394
+
395
+ The default `featherdown` entry does not render Mermaid in the browser. If your app needs live Mermaid previews, parse Markdown first, then hydrate `code.language-mermaid` blocks with the `mermaid` package in your own app code. This keeps Mermaid out of Featherdown's browser bundle. Use `featherdown/node` when you want build-time SVG output.
396
+
397
+ ```ts
398
+ import mermaid from "mermaid";
399
+
400
+ const result = await featherdown.parse(markdown);
401
+ mermaid.initialize({ startOnLoad: false, securityLevel: "strict" });
402
+ ```
403
+
404
+ ## Public API (summary)
405
+
406
+ **Primary**
407
+
408
+ - **`Featherdown`**, **`FeatherdownOptions`**, **`FeatherdownParseOptions`**, **`FeatherdownResult`**, and related types from **`featherdown`**.
409
+
410
+ **Node**
411
+
412
+ - **`Featherdown`** from **`featherdown/node`** with optional **`NodeFeatherdownOptions`** / Mermaid config.
413
+
414
+ **Styles (package exports)**
415
+
416
+ - `featherdown/styles.css`, `featherdown/styles/base.css`, `featherdown/styles/katex.css`, `featherdown/styles/code.css`, `featherdown/styles/highlight.css`
417
+
418
+ **Compatibility**
419
+
420
+ - Legacy render helpers and **`parseMarkdownFile`** on the default entry; **`renderMarkdownToHtmlWithMermaid`** on **`featherdown/node`**; **`featherdown/advanced`** for processor/plugins.
167
421
 
168
422
  ## Scripts
169
423
 
170
- | Script | Description |
171
- | ---------------------- | --------------------------------- |
172
- | `npm run build` | Build ESM artifacts in `dist/` |
173
- | `npm test` | Run Vitest once |
174
- | `npm run test:watch` | Run Vitest in watch mode |
175
- | `npm run lint` | Run ESLint |
176
- | `npm run typecheck` | Run TypeScript checks |
177
- | `npm run test:exports` | Build and run export smoke checks |
424
+ | Script | Description |
425
+ | --- | --- |
426
+ | `npm run build` | Build ESM artifacts in `dist/` |
427
+ | `npm test` | Run Vitest once |
428
+ | `npm run test:watch` | Vitest watch mode |
429
+ | `npm run lint` | ESLint |
430
+ | `npm run typecheck` | TypeScript `--noEmit` |
431
+ | `npm run test:exports` | Build + export smoke checks |
432
+
433
+ ## Site
434
+
435
+ A demo site lives in **`site/`**.
436
+
437
+ ```bash
438
+ npm run site:install
439
+ npm run site:dev
440
+ ```
441
+
442
+ Build:
443
+
444
+ ```bash
445
+ npm run site:build
446
+ ```
447
+
448
+ GitHub Pages base path:
449
+
450
+ ```bash
451
+ SITE_BASE_PATH=/featherdown/ npm run site:build
452
+ ```
178
453
 
179
454
  ## Maintainers
180
455
 
181
- CI and publishing are described in [RELEASING.md](./RELEASING.md).
456
+ CI and publishing: [RELEASING.md](./RELEASING.md).
182
457
 
183
458
  ## License
184
459
 
@@ -0,0 +1,75 @@
1
+ import { R as RenderDiagnostic, b as RenderMarkdownOptions } from './types-Blk9BrZ4.js';
2
+ import { Root as Root$1 } from 'hast';
3
+ import { Root } from 'mdast';
4
+ import { Processor, Plugin } from 'unified';
5
+
6
+ /**
7
+ * Emits a non-fatal rendering diagnostic.
8
+ */
9
+ type DiagnosticEmitter = (d: RenderDiagnostic) => void;
10
+
11
+ /** Optional pipeline stages for {@link Featherdown}; omit for legacy all-on behavior. */
12
+ type MarkdownProcessorFeatureGates = {
13
+ math: boolean;
14
+ code: boolean;
15
+ codeHighlighting: boolean;
16
+ charts: boolean;
17
+ sanitize: boolean;
18
+ };
19
+ type InternalOptions = RenderMarkdownOptions & {
20
+ emitDiagnostic?: DiagnosticEmitter;
21
+ preserveHeadingCustomIdMarker?: boolean;
22
+ features?: MarkdownProcessorFeatureGates;
23
+ };
24
+ /**
25
+ * Build the default browser-safe unified processor used by public APIs.
26
+ *
27
+ * Internal helper that wires remark/rehype plugins for math, highlighting,
28
+ * sanitization, heading ids, chart placeholders, and image rewriting.
29
+ */
30
+ declare function createMarkdownProcessorInternal(options?: InternalOptions): Processor<Root, Root, Root$1>;
31
+
32
+ /**
33
+ * Create a browser-safe unified processor configured for featherdown defaults.
34
+ *
35
+ * Advanced API for users who need direct unified processor control.
36
+ * Most users should use `Featherdown`.
37
+ *
38
+ * This entrypoint exports the lower-level processor factory so callers can run
39
+ * custom `.process()` flows while still using the package's sanitization and
40
+ * plugin pipeline. Prefer importing from `featherdown/advanced` when wiring
41
+ * unified integrations.
42
+ */
43
+ declare function createMarkdownProcessor(options?: RenderMarkdownOptions): ReturnType<typeof createMarkdownProcessorInternal>;
44
+
45
+ /**
46
+ * Advanced rehype plugin: converts supported `chart-*` fenced JSON blocks into
47
+ * chart mount placeholders in the output HTML tree.
48
+ *
49
+ * Most users should use `Featherdown`, which includes this pipeline by default.
50
+ * Prefer importing from `featherdown/advanced` for direct rehype integration.
51
+ */
52
+ /**
53
+ * Replaces supported `chart-…` fenced JSON blocks with a mount placeholder.
54
+ * Invalid JSON leaves the original `<pre><code>` unchanged.
55
+ */
56
+ declare const rehypeChartBlocks: Plugin<[], Root$1>;
57
+
58
+ /**
59
+ * Advanced rehype plugin: annotates images and can rewrite `src` using
60
+ * caller-provided manifest mappings.
61
+ *
62
+ * Most users should use `Featherdown`, which includes this pipeline by default.
63
+ * Prefer importing from `featherdown/advanced` for direct rehype integration.
64
+ */
65
+ /**
66
+ * Options accepted by `rehypeCdnImages`.
67
+ */
68
+ type RehypeCdnImagesOptions = RenderMarkdownOptions;
69
+ /**
70
+ * Adds `markdown-inline-img` to all images and optionally rewrites `src` using
71
+ * caller-provided manifest data.
72
+ */
73
+ declare const rehypeCdnImages: Plugin<[RehypeCdnImagesOptions?], Root$1>;
74
+
75
+ export { createMarkdownProcessor, rehypeCdnImages, rehypeChartBlocks };
@@ -0,0 +1,4 @@
1
+ export { createMarkdownProcessor, rehypeCdnImages, rehypeChartBlocks } from './chunk-DNLCIOR6.js';
2
+ import './chunk-YKLQHPRB.js';
3
+ //# sourceMappingURL=advanced.js.map
4
+ //# sourceMappingURL=advanced.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"advanced.js"}