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 +382 -107
- package/dist/advanced.d.ts +75 -0
- package/dist/advanced.js +4 -0
- package/dist/advanced.js.map +1 -0
- package/dist/chunk-CWUDY7YI.js +558 -0
- package/dist/chunk-CWUDY7YI.js.map +1 -0
- package/dist/chunk-DNLCIOR6.js +16 -0
- package/dist/chunk-DNLCIOR6.js.map +1 -0
- package/dist/chunk-YKLQHPRB.js +711 -0
- package/dist/chunk-YKLQHPRB.js.map +1 -0
- package/dist/featherdownDiagnosticsError-CE9gG3W7.d.ts +19 -0
- package/dist/index.d.ts +82 -29
- package/dist/index.js +17 -80
- package/dist/index.js.map +1 -1
- package/dist/node.d.ts +45 -2
- package/dist/node.js +232 -3
- package/dist/node.js.map +1 -1
- package/dist/types-Blk9BrZ4.d.ts +250 -0
- package/package.json +27 -4
- package/styles/base.css +262 -0
- package/styles/code.css +73 -0
- package/styles/highlight.css +5 -0
- package/styles/katex.css +7 -0
- package/styles.css +4 -0
- 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,10 @@
|
|
|
1
1
|
# featherdown
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
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
|
-
|
|
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 {
|
|
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
|
-
|
|
34
|
+
The default entry is browser-safe and does **not** include Mermaid rendering.
|
|
20
35
|
|
|
21
|
-
|
|
36
|
+
## Rendering Markdown
|
|
22
37
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
51
|
+
### Image manifest example
|
|
29
52
|
|
|
30
53
|
```ts
|
|
31
|
-
|
|
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
|
|
64
|
+
const result = await featherdown.parse(markdown);
|
|
34
65
|
```
|
|
35
66
|
|
|
36
|
-
|
|
67
|
+
## Result object
|
|
37
68
|
|
|
38
|
-
|
|
69
|
+
`Featherdown.parse()` resolves to a **`FeatherdownResult`**. Commonly used fields:
|
|
39
70
|
|
|
40
|
-
|
|
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
|
-
|
|
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
|
-
|
|
46
|
-
"```chart-line\nnot json\n```",
|
|
47
|
-
);
|
|
87
|
+
## Styles
|
|
48
88
|
|
|
49
|
-
|
|
50
|
-
console.log(diagnostics);
|
|
51
|
-
````
|
|
89
|
+
Official styles target the **`featherdown-content`** wrapper class and related HTML contracts.
|
|
52
90
|
|
|
53
|
-
|
|
91
|
+
### All-in (recommended starting point)
|
|
54
92
|
|
|
55
|
-
|
|
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
|
|
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
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
|
|
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
|
-
|
|
119
|
+
### Custom themes
|
|
120
|
+
|
|
121
|
+
You can start from Featherdown's baseline styles and override them:
|
|
68
122
|
|
|
69
123
|
```ts
|
|
70
|
-
import
|
|
71
|
-
import
|
|
72
|
-
import
|
|
73
|
-
|
|
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
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
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
|
-
|
|
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
|
-
|
|
187
|
+
const featherdown = new Featherdown({
|
|
188
|
+
diagnostics: "warn",
|
|
189
|
+
});
|
|
108
190
|
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
242
|
+
## Code blocks
|
|
128
243
|
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
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
|
-
|
|
138
|
-
The `node` Mermaid subpath is npm-focused and is not part of the JSR export surface.
|
|
252
|
+
## Math
|
|
139
253
|
|
|
140
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
264
|
+
## Charts, callouts, and publishing features
|
|
147
265
|
|
|
148
|
-
|
|
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
|
-
|
|
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
|
-
|
|
270
|
+
### Callouts (admonitions)
|
|
155
271
|
|
|
156
|
-
|
|
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
|
-
|
|
274
|
+
### Images
|
|
165
275
|
|
|
166
|
-
|
|
276
|
+
Optional **`manifest`** + **`kind`** + **`slug`** rewrite relative `` 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
|
|
171
|
-
|
|
|
172
|
-
| `npm run build`
|
|
173
|
-
| `npm test`
|
|
174
|
-
| `npm run test:watch`
|
|
175
|
-
| `npm run lint`
|
|
176
|
-
| `npm run typecheck`
|
|
177
|
-
| `npm run test:exports` | Build
|
|
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
|
|
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 };
|
package/dist/advanced.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"advanced.js"}
|