@tiaforge-ui/sinter-markdown 0.0.0-stage → 0.20.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.
Files changed (36) hide show
  1. package/README.md +305 -2
  2. package/docs/markdown.md +258 -0
  3. package/docs/recipes/article-with-comments.html +28 -0
  4. package/llms.txt +44 -0
  5. package/package.json +65 -4
  6. package/sinter/components/internal/md-block.html +7 -0
  7. package/sinter/components/internal/md-blockquote.html +3 -0
  8. package/sinter/components/internal/md-break.html +3 -0
  9. package/sinter/components/internal/md-code.html +4 -0
  10. package/sinter/components/internal/md-delete.html +3 -0
  11. package/sinter/components/internal/md-details.html +4 -0
  12. package/sinter/components/internal/md-emphasis.html +3 -0
  13. package/sinter/components/internal/md-heading.html +4 -0
  14. package/sinter/components/internal/md-image.html +9 -0
  15. package/sinter/components/internal/md-inline-code.html +3 -0
  16. package/sinter/components/internal/md-kbd.html +3 -0
  17. package/sinter/components/internal/md-link.html +4 -0
  18. package/sinter/components/internal/md-list-item.html +4 -0
  19. package/sinter/components/internal/md-list.html +4 -0
  20. package/sinter/components/internal/md-mark.html +3 -0
  21. package/sinter/components/internal/md-paragraph.html +3 -0
  22. package/sinter/components/internal/md-phrasing.html +9 -0
  23. package/sinter/components/internal/md-strong.html +3 -0
  24. package/sinter/components/internal/md-sub.html +3 -0
  25. package/sinter/components/internal/md-sup.html +3 -0
  26. package/sinter/components/internal/md-table.html +9 -0
  27. package/sinter/components/internal/md-thematic-break.html +3 -0
  28. package/sinter/components/md-doc.html +10 -0
  29. package/sinter/components/md-inline.html +11 -0
  30. package/sinter/index.ts +5 -0
  31. package/sinter/parse.ts +270 -0
  32. package/sinter/parser.d.ts +19 -0
  33. package/sinter/parser.js +2872 -0
  34. package/sinter/sinter.helpers.ts +10 -0
  35. package/sinter/sinter.types.ts +209 -0
  36. package/sinter/tree.ts +61 -0
package/README.md CHANGED
@@ -1,3 +1,306 @@
1
- # Temporary Holding Version
1
+ # @tiaforge-ui/sinter-markdown
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Markdown for [sinter](https://github.com/tiaforge/sinter): a parser, `md.parse`, that returns a tree,
4
+ and components, `<md-doc>` and `<md-inline>`, that render it. Markdown from a file in the repo is plain
5
+ HTML at build time; markdown from an API is parsed in the browser. How a kind of node looks is changed
6
+ with slots.
7
+
8
+ ```html
9
+ <sn-resource name="post" src="file:./post.md"></sn-resource>
10
+ <main data-sn-let="{ doc: md.parse(post.body) }">
11
+ <md-doc data-sn-prop="{ doc }"></md-doc>
12
+ </main>
13
+ ```
14
+
15
+ **Using it:** [docs/markdown.md](docs/markdown.md), and the [recipe](docs/recipes/article-with-comments.html)
16
+ with an article and its comments on one page.
17
+
18
+ This package is also the example to copy when you write a [component
19
+ library](https://github.com/tiaforge/sinter/blob/main/docs/libraries.md) of your own. The rest of this
20
+ file is about that: what each part is, why it is where it is, and how the library is checked and tested.
21
+
22
+ ## Using it in an app
23
+
24
+ ```sh
25
+ npm install @tiaforge-ui/sinter-markdown
26
+ ```
27
+
28
+ ```js
29
+ // vite.config.js: the package is a component library
30
+ sinter({ components: ['@tiaforge-ui/sinter-markdown'] })
31
+ ```
32
+
33
+ ```ts
34
+ // src/sinter.helpers.ts: its helpers, under a namespace the app chooses
35
+ export * as md from '@tiaforge-ui/sinter-markdown';
36
+ ```
37
+
38
+ ```ts
39
+ // src/sinter.types.ts: its types, where the app's own declarations name them
40
+ export type { Root } from '@tiaforge-ui/sinter-markdown';
41
+ ```
42
+
43
+ That is all an app does with a library: name it in the config, re-export its helpers and types. The
44
+ public components (`<md-doc>`, `<md-inline>`) are then tags on every page. To make the parser load on
45
+ demand, the app also lists the package in `sinter({ lazy })` ([docs](docs/markdown.md#three-places-one-function)).
46
+
47
+ ## The package
48
+
49
+ ```
50
+ package.json name, "sinter": "./sinter", exports, the sinter versions it supports
51
+ sinter/ the library's source, laid out like an app's src/
52
+ components/ public: what apps use
53
+ md-doc.html a document: block content, and the slots an app fills
54
+ md-inline.html one line: phrasing content in a <span>, the slots it can place
55
+ internal/ the library's own: one component per node type
56
+ md-block.html one block, by its type: the only place block content is dispatched
57
+ md-phrasing.html one inline node but text, by its type: the only place phrasing content is
58
+ md-heading.html its root is the `heading` slot, whose default is an if chain over the depth
59
+ md-list.html an if chain over `ordered`
60
+ md-paragraph.html …
61
+ sinter.helpers.ts the helpers: re-exports from the two modules below
62
+ parse.ts md.parse: imports the parser, reduces its tree, applies the options
63
+ tree.ts md.headings, md.text: read a tree, import no parser
64
+ parser.js the parser, prebundled (generated by scripts/build-parser.mjs; committed)
65
+ parser.d.ts its types
66
+ sinter.types.ts the tree's types: what the components and apps name
67
+ index.ts the package's entry: the helpers and the types
68
+ scripts/
69
+ parser-entry.js what parser.js bundles: markdown-it, configured; it returns tokens
70
+ autolink.js GFM's autolinks, a rule parser-entry.js adds to markdown-it
71
+ entities.js … what the parser bundles in place of markdown-it's dependencies (README, "The parser")
72
+ build-parser.mjs builds parser.js; --check fails when it is out of date
73
+ fixtures/ pages that use the public components, for the library's own check
74
+ index.html … an article from a file, every slot filled, comments from an API
75
+ sinter.helpers.ts the fixture pages' helpers module, as an app writes its own
76
+ sinter.types.ts and their types module
77
+ vite.config.ts configures the fixture pages as an app would (their helpers and types)
78
+ test/ the package's tests (vitest)
79
+ docs/ the docs page and the recipe
80
+ ```
81
+
82
+ ### `package.json`
83
+
84
+ ```json
85
+ {
86
+ "name": "@tiaforge-ui/sinter-markdown",
87
+ "type": "module",
88
+ "sinter": "./sinter",
89
+ "exports": {
90
+ ".": "./sinter/index.ts",
91
+ "./parser": "./sinter/parser.js"
92
+ },
93
+ "peerDependencies": { "@tiaforge-ui/sinter": ">=0.18.0 <1" }
94
+ }
95
+ ```
96
+
97
+ - **`"sinter": "./sinter"`** names the folder that sinter reads as the library's source. A library
98
+ ships source, not built output: the app's sinter compiles its components as it compiles the app's
99
+ own, so they get build-time constants, the early script, type checks and scoped styles.
100
+ - **`exports`.** `.` is the entry, which re-exports the helpers: the app's
101
+ `export * as md from '@tiaforge-ui/sinter-markdown'` is followed through it to each helper's own
102
+ module. `./parser` lets `parse.ts` import the parser by the package's name (below).
103
+ - **`peerDependencies`** lists the sinter versions the library supports. The app's sinter warns when
104
+ its version is outside the range (`SN537`). sinter is a peer, never a dependency: the app has one
105
+ sinter, and the library's markup is compiled by it.
106
+ - **`devDependencies`** hold what builds and tests the library: the parser's sources (bundled into
107
+ `parser.js`, so an app installs none of them), the bundler, and a sinter to test against (`file:../..`
108
+ in this repository, the framework's own build).
109
+
110
+ ### The components
111
+
112
+ - **Public and internal.** `components/` is what apps use; `components/internal/` is the library's own
113
+ (`SN339` if an app uses one). Every name starts with the library's prefix, `md-`, which the library
114
+ owns: no app component and no other library may use it.
115
+ - **The contract is in the public files.** `md-doc.html` and `md-inline.html` declare the slots an app
116
+ fills (`heading: Slot<{ node: Heading }>`, …); the internal components place them
117
+ (`<slot name="heading" data-sn-prop="{ node }">`) without declaring them, as [tree
118
+ slots](https://github.com/tiaforge/sinter/blob/main/docs/components.md#tree-slots). Adding a slot
119
+ later is additive; renaming or removing one breaks apps.
120
+ - **Roots.** A component's root renders at most one element. A heading is an if chain over its depth,
121
+ a list over `ordered`, and a node an app can change has its slot as its root, with the default
122
+ inside. A root that is not a plain element costs nothing when a constant decides it.
123
+ - **Dispatch in one place.** `md-block` chooses a block's component by its type, and `md-phrasing`
124
+ an inline node's: each is a component whose root is `<sn-component use="{ paragraph: 'md-paragraph',
125
+ … }[node.type]">`, one choice per node whatever the number of candidates. Every loop over children
126
+ renders `<md-block>` or `<md-phrasing>` for each, so each map is written once. A component whose root
127
+ is the choice adds no element and no anchor of its own. In a library with slots the map (or
128
+ convention) form is required, so sinter knows every candidate (`SN312`).
129
+ - **Text runs** are `<template data-sn-text>`, a text node with no element around it. A root cannot be
130
+ text, so text runs are not a component: each loop over phrasing content writes
131
+ `<template data-sn-if="n.type === 'text'">` for them and passes every other node to `<md-phrasing>`.
132
+ `test/components.test.ts` checks that every such loop has that form.
133
+ - **Phrasing roots for phrasing places.** `md-inline` is used inside headings, labels and paragraphs,
134
+ so its root is a `<span>` and everything in it is phrasing content. A `<div>` there is invalid, and
135
+ in a `<p>` the HTML parser would close the paragraph, so a page built at build time would be
136
+ reparsed into a different tree. Since it renders no headings, code blocks, quotes or tables, it
137
+ declares only the slots it places (`link`, `image`, `inlineCode`): every declared slot must be placed
138
+ (`SN331`).
139
+
140
+ ### The helpers
141
+
142
+ - **Two modules, one namespace.** `md.parse` is in `parse.ts`, which imports the parser; `md.headings`
143
+ and `md.text` are in `tree.ts`, which does not. sinter decides per module whether a helper waits for
144
+ a lazy package, so with the parser lazy, `md.headings` stays an ordinary helper that renders early
145
+ and folds at build time. `sinter.helpers.ts` re-exports both, and the entry re-exports it.
146
+ - **Pure.** A helper over constants (a `file:` resource) runs at build time, if everything it reaches
147
+ uses only the language's own globals and `URL`, `URLSearchParams`, `structuredClone`, `TextEncoder`
148
+ and `TextDecoder`. `parse.ts` and `tree.ts` are written that way, and so is the parser; sinter's check
149
+ reads a top-level `const x = memo(…)` as a unit of its own, so the memo's cache does not stop
150
+ md.parse from folding.
151
+ - **md.parse keeps its trees.** In the browser a let or a prop is its expression, evaluated at every
152
+ read, and md-doc's components read their `doc` at every node: an article's let is read hundreds of
153
+ times per render. So `parse.ts` wraps the parse in sinter's `memo()`
154
+ (`@tiaforge-ui/sinter/memo`), and the contract is:
155
+ - the same source and the same options give the same tree object, parsed once. The options are
156
+ normalized first (defaults filled in, `base` with its trailing `/`), so `{}` and
157
+ `{ html: 'text' }` share a tree;
158
+ - the tree is deep-frozen and shared by every caller, in production too: change a copy
159
+ (`structuredClone(doc)`);
160
+ - the cache holds about 8 MiB of trees, the least recently used going first; a source whose tree was
161
+ dropped is parsed again, into a new tree;
162
+ - an invalid option throws at each call, and nothing is kept.
163
+
164
+ Measured in Node on the spike's 47.5 kB article: a parse takes about 67 ms, a read of a kept tree
165
+ about 0.01 ms. On its recipe page, the browser parses each distinct source once
166
+ (`test/parses.test.ts`); without the memo it parsed 16 times for 6 sources. Each bundle keeps its own
167
+ trees (the page module, the early file) and the build its own, at build time.
168
+ - **md.headings and md.text walk the tree at each read**, with no cache: they take a tree, an object,
169
+ which `memo()` would call through anyway. On the 47.5 kB article they take about 0.09 and 0.2 ms, on
170
+ 50 comments about 0.01 and 0.05 ms together; a page reads them a few times per render, not per node.
171
+ - **Nothing per node is kept in the components.** None has state, a script or a handler, so two
172
+ comments with the same body share one frozen tree and render it twice, each in its own rows.
173
+ - **The library's components cannot call its helpers.** In markup, helpers are called through the
174
+ namespace the app chose (`md.` here, but the app could write `export * as markdown from …`). What a
175
+ component needs is computed into the data instead: `md.parse` writes each heading's `slug`.
176
+
177
+ ### The parser: one prebundled module
178
+
179
+ `parser.js` is markdown-it (CommonMark, GFM tables and `~~strikethrough~~`) with GFM's autolinks
180
+ (`scripts/autolink.js`), configured for `md.parse` and bundled into one file by `scripts/build-parser.mjs`:
181
+ 21.8 kB minified and gzipped (19.5 kB brotli). It returns markdown-it's tokens, and `parse.ts` builds the
182
+ tree from them in one pass, task lists and the options included: there is no intermediate tree (an mdast
183
+ before the library's own, and a walk over it).
184
+
185
+ - **markdown-it, not micromark**, for speed: on a 47.5 kB article it parses in 23 ms on a cold start
186
+ where micromark took 160 ms, which was most of an API article's time to first render. GFM is what
187
+ markdown-it gives, and GFM's autolinks: `~one tilde~` is not strikethrough. Everything CommonMark
188
+ specifies gives the same tree as micromark did, except a code span's line endings, which are spaces,
189
+ as CommonMark renders them.
190
+ - **What `md.parse` never runs is left out**, so the bundle holds markdown-it's parsers and rules and
191
+ no more: its renderer, the typographer's rules (`typographer` is off) and its linkify are
192
+ `scripts/unused.js`; mdurl (`scripts/mdurl.js`) and punycode (`scripts/punycode.js`) are left out
193
+ because the tree keeps a link's destination as written, so the parser normalizes no URL; uc.micro's
194
+ tables are two regexes (`scripts/uc-micro.js`: emphasis needs Unicode punctuation and symbols, `\p{P}`
195
+ and `\p{S}`). The parser was 34.5 kB with them. `test/parse.test.ts` checks which of markdown-it's
196
+ modules are in it.
197
+ - **Autolinks are GFM's** (`scripts/autolink.js`, a core rule run after markdown-it's): `www.`,
198
+ `http(s)://` and `ftp://` URLs, emails, and `mailto:` and `xmpp:` emails, as github.com finds them.
199
+ A bare domain is not a link (`example.com`, `config.md`), a bare email is
200
+ (`foo@bar.baz`, to `mailto:foo@bar.baz`), and the end of a link is trimmed as GFM specifies: trailing punctuation, a
201
+ `)` with no `(`, an entity-like `&hl;`. It passes the GFM spec's and cmark-gfm's autolink examples,
202
+ which markdown-it's linkify (linkify-it) got about half of, and is about 1 kB where linkify-it and its
203
+ Unicode tables were about 5.7 kB. Only those schemes come out. It is linear in the text: every match
204
+ moves the scan forward and a link's end is trimmed by an index; `test/parse.test.ts` parses long runs
205
+ that a backtracking scan revisits (`a.a.a.…`, `www.a.b)))…`, `&a;&a;…`) within a second each (each
206
+ takes under 0.1 s).
207
+ - **Entities decode from a table** (`character-entities`, through `scripts/entities.js`), never through
208
+ the DOM, so the parser works under Trusted Types (`require-trusted-types-for 'script'`). It is the
209
+ table micromark used, packed by `scripts/build-parser.mjs`: sorted by code point, each entry its
210
+ distance from the one before, about 7.5 kB gzip where the table as an object is 11.5 and
211
+ markdown-it's own (`entities`, a packed trie) 21. It is unpacked once, when the parser loads.
212
+ - sinter's build-time check follows one module that uses no browser global, so `md.parse` folds over
213
+ a `file:` resource.
214
+
215
+ **Committed, not built on install.** The built file is in the repository and in the published package,
216
+ and a test fails when it is not what the script writes from the locked dependencies
217
+ (`npm run build:parser -- --check`). Building on install would need the bundler and the parser's
218
+ sources in every app's install, and a step that can fail there; a committed file is reviewed like any
219
+ change, and is the same file in every app. After updating a parser dependency, run
220
+ `npm run build:parser` and commit the result.
221
+
222
+ `parse.ts` imports it as `@tiaforge-ui/sinter-markdown/parser`, through the package's own `exports`,
223
+ not as `./parser.js`: an app makes a package lazy by name (`sinter({ lazy })`), and sinter matches lazy
224
+ packages by import specifier.
225
+
226
+ ### Fixture pages
227
+
228
+ A library has no pages, and sinter checks a component through the pages that use it. `fixtures/*.html`
229
+ are pages that use the public components with the cases the library supports: an article from a
230
+ file, every slot filled, comments from an API. `npx sinter check` in this folder takes them as its
231
+ pages (there is no Vite config with pages of its own), configures the package as a library of
232
+ `sinter({ components })`, compiles and type-checks them, and checks the library's rules: every declared
233
+ slot is placed somewhere (`SN331`), `<sn-component use>` takes a map (`SN312`), internal components are
234
+ used only inside the library (`SN339`). Each app's build checks the same rules again.
235
+
236
+ `vite.config.ts` points the check at `fixtures/sinter.helpers.ts` and `fixtures/sinter.types.ts`, which
237
+ are what an app would write: the package re-exported by its own name (`export * as md from
238
+ '@tiaforge-ui/sinter-markdown'`, which works because the package has `exports`).
239
+
240
+ ## Checking and testing
241
+
242
+ ```sh
243
+ npm install # in this folder
244
+ npx sinter check # the fixture pages: compiled, type-checked, the library's rules
245
+ npm run typecheck # parse.ts, tree.ts and the tests
246
+ npm test # vitest
247
+ ```
248
+
249
+ In this repository the package is tested against the framework's own build: run `npm ci && npm run
250
+ build` at the root first. CI runs the package's tests in a job of its own, after the framework's build.
251
+
252
+ | Test | What it covers |
253
+ | --- | --- |
254
+ | `test/parse.test.ts` | `md.parse` and its options, `md.headings`, `md.text`; that `tree.ts` imports no parser; that `parser.js` is up to date and decodes entities with its table |
255
+ | `test/check.test.ts` | `sinter check` over the fixture pages: no error, no warning |
256
+ | `test/static.test.ts` | a page with `<sn-resource src="file:./post.md">` built with `sinter({ static })`: no JavaScript, every node type as plain HTML, `html: 'allow'`, the table of contents, a local image optimized |
257
+ | `test/parses.test.ts` | the recipe in Chromium with the parser counting what it tokenizes: one parse per distinct source, none after a change elsewhere on the page or for a new comment with a body already parsed |
258
+ | `test/components.test.ts` | the dispatch maps against the `Block` and `Inline` unions and the component files, and the form of every loop over phrasing content |
259
+ | `test/api.test.ts` | the recipe built as an app, served with an API, in Chromium under `script-src 'self'; style-src 'self'; require-trusted-types-for 'script'`, failing on any violation or console error: entities, the user-content policy, the link fill, unsafe URLs, images; with the parser loaded with the page and with it lazy |
260
+
261
+ `test/app.ts` makes a throwaway app with the package linked into its `node_modules`, as a workspace or
262
+ `npm link` does: the tests use the package the way an app does.
263
+
264
+ ## Notes for library authors
265
+
266
+ What writing this library taught, beyond [the library docs](https://github.com/tiaforge/sinter/blob/main/docs/libraries.md):
267
+
268
+ - **Whitespace between tags is text.** Inside a component, a newline and indentation between two tags
269
+ is a text node in the page, once per row of a loop: in phrasing content it shows as a space. The
270
+ components here write the markup inside each root without whitespace between tags.
271
+ - **Text runs first.** For the children of a paragraph, `<template data-sn-if="n.type === 'text'">` the
272
+ text, `<template data-sn-else>` the choice, costs one anchor per text run. The choice first with a
273
+ `data-sn-else` for text costs two: the choice's anchor, empty for text, and the else's own.
274
+ `sinter check` narrows each branch by its condition, so `n.value` and `n.type` are typed in both.
275
+ - **An id from data starts with a literal.** `data-sn-attr="{ id: node.slug }"` warns (`SN503`): an id
276
+ written from data can shadow a global another script reads. The anchors are `'md-' + node.slug`, and
277
+ `md.headings` returns the same ids, so a table of contents and the anchors agree.
278
+ - **A slot inside a `<table>` cannot be written in a fill.** The HTML parser moves a `<slot>` written
279
+ inside a `<table>` out of it, so a fill cannot place a table's rows. The `table` slot's default is
280
+ therefore a `<div class="md-table">` around the table: a fill places the whole table, or renders its
281
+ own.
282
+ - **An image from user content is a plain `<img>`.** `md-image` binds `srcset: null`, which tells sinter
283
+ not to send the image through the app's resizing service; an app that wants it resized fills the
284
+ `image` slot.
285
+ - **A candidate that cannot match is a warning.** Under the else of `data-sn-if="b.type === 'paragraph'"`,
286
+ a map that still lists `paragraph:` names a component that never renders there (`SN538`).
287
+ - **Count what renders.** A separator between items (md-inline's space between paragraphs) goes
288
+ before every item but the first of the list that renders: md-inline loops over
289
+ `doc.children.filter((x) => x.type === 'paragraph' || x.type === 'heading')`, so a list it leaves out
290
+ first adds no leading space. TypeScript narrows the filtered items to `Paragraph | Heading`.
291
+
292
+ ### Adding a node type
293
+
294
+ 1. Its interface in `sinter/sinter.types.ts`, with its `type` literal, and the interface in the `Block`
295
+ or `Inline` union.
296
+ 2. Its conversion from markdown-it's tokens in `sinter/parse.ts` (`blocks()` or `inlines()`), and its text in `md.text`
297
+ (`sinter/tree.ts`) if it has no `children` or `value`.
298
+ 3. Its component in `sinter/components/internal/`, named with the `md-` prefix.
299
+ 4. One entry in the map of `md-block.html` or `md-phrasing.html`. `test/components.test.ts` fails until
300
+ the map and the union agree and the component exists.
301
+ 5. If apps should be able to change it, a slot: declared in `md-doc.html` (and `md-inline.html` for
302
+ phrasing content), placed as the new component's root.
303
+
304
+ ## License
305
+
306
+ MIT
@@ -0,0 +1,258 @@
1
+ # Markdown
2
+
3
+ `@tiaforge-ui/sinter-markdown` renders markdown in a sinter app: from a file in the repo, as plain
4
+ HTML at build time, and from an API, parsed in the browser. It is a [component
5
+ library](https://github.com/tiaforge/sinter/blob/main/docs/libraries.md): a parser, `md.parse`, that
6
+ returns a tree, and components, `<md-doc>` and `<md-inline>`, that render it. How a kind of node looks is
7
+ changed with slots.
8
+
9
+ ```html
10
+ <sn-resource name="post" src="file:./post.md"></sn-resource>
11
+ <main data-sn-let="{ doc: md.parse(post.body) }">
12
+ <md-doc data-sn-prop="{ doc }"></md-doc>
13
+ </main>
14
+ ```
15
+
16
+ A markdown file's value is its frontmatter's fields and `body`, the markdown after the frontmatter
17
+ (`post.title`, `post.body`), and a glob is a list of them, one per file
18
+ ([files](https://github.com/tiaforge/sinter/blob/main/docs/resources.md#files)).
19
+
20
+ The [recipe](recipes/article-with-comments.html) puts an article and its comments on one page.
21
+
22
+ ## Setup
23
+
24
+ ```sh
25
+ npm install @tiaforge-ui/sinter-markdown
26
+ ```
27
+
28
+ ```js
29
+ // vite.config.js
30
+ import { defineConfig } from 'vite';
31
+ import sinter from '@tiaforge-ui/sinter/vite';
32
+
33
+ export default defineConfig({
34
+ plugins: [sinter({ components: ['@tiaforge-ui/sinter-markdown'] })],
35
+ });
36
+ ```
37
+
38
+ ```ts
39
+ // src/sinter.helpers.ts: the helpers, as the namespace `md`
40
+ export * as md from '@tiaforge-ui/sinter-markdown';
41
+
42
+ // src/sinter.types.ts: the tree's types, for your own declarations
43
+ export type { Root, Heading, Link, TocEntry } from '@tiaforge-ui/sinter-markdown';
44
+ ```
45
+
46
+ ## Three places, one function
47
+
48
+ `md.parse(source, options)` is a pure function, so sinter runs it wherever its argument is:
49
+
50
+ | Markdown | Where it is parsed | What the page ships |
51
+ | --- | --- | --- |
52
+ | A file: `src="file:./post.md"` | at build time | the article as plain HTML, no JavaScript ([static pages](https://github.com/tiaforge/sinter/blob/main/docs/static-pages.md)) |
53
+ | A string from an API, in a `data-sn-let` | in the browser, once per source and options (md.parse keeps its trees) | the parser with the page |
54
+ | The same, with the parser lazy | in the browser, once the parser has loaded | the parser in a chunk of its own, loaded when a let first needs it |
55
+ | A tree from an API you control (`md.parse` run on the server, `<md-doc data-sn-prop="{ doc: article.doc }">`) | on the server: the API sends the tree instead of the markdown | no parser ([Performance](#performance)); the parse moves to the server, or to wherever the API stores the tree |
56
+
57
+ To make the parser lazy, list the package in `lazy`:
58
+
59
+ ```js
60
+ sinter({ components: ['@tiaforge-ui/sinter-markdown'], lazy: ['@tiaforge-ui/sinter-markdown'] })
61
+ ```
62
+
63
+ A let that calls `md.parse` is then `undefined` until the parser has arrived, and its arrival renders
64
+ what reads the let; `<md-doc>` with no `doc` renders an empty `<div class="md">`. `md.headings` and
65
+ `md.text` live in a module that does not import the parser, so they stay ordinary helpers either way.
66
+ Measure first: the parser is about 22 kB gzip, and a page whose main content is markdown may reach
67
+ its LCP sooner with the parser loaded with the page (or with `data-sn-preload`).
68
+
69
+ With embedded data, a binding over `md.parse` renders in the early script, so the parser is in the page's early
70
+ file: over twice sinter's early budget (`SN523`). For a page whose main content is the markdown, that can be the
71
+ better trade: on RealWorld's article through sinter-axum (Lighthouse mobile), the early file was 30.5 kB gzip, the
72
+ first paint did not move, and the LCP was the first paint, 1,359 ms, against 2,127 ms with the body rendered when
73
+ the page module mounts. The parser is then downloaded twice (the early file and the page module). Raise the
74
+ budget for it (`sinter({ earlyBudget })`), as the RealWorld example does ([its
75
+ README](https://github.com/tiaforge/sinter/blob/main/examples/realworld/README.md)); or keep the body out with
76
+ `data-sn-early="off"` on the `<md-doc>`, and keep what follows the body out of the layout until it renders.
77
+ Measure first: a page whose markdown is not its main content pays the early file for nothing. Markdown from an
78
+ API is in the first frame without a parser when the API sends the tree (`md.parse` run on the server), which
79
+ `<md-doc>` renders like any other data.
80
+
81
+ ## `md.parse(source, options)`
82
+
83
+ `source` is the markdown (`null` and `undefined` are an empty document). The result is a tree of
84
+ plain data, typed by the package (`Root`): CommonMark, and GFM tables, task lists, strikethrough and
85
+ autolinks (`www.example.com`, `https://…`, `foo@bar.baz`, as github.com links them; a bare
86
+ `example.com` is text). Footnotes are not supported. Positions are left out, and so are definitions: references
87
+ (`[text][ref]`) come back as links and images. Entities are decoded (`&amp;` is `&`).
88
+
89
+ The options are the policy for one use. What a document may not contain is taken out of the tree, so
90
+ what reads the tree (a table of contents) agrees with what is shown:
91
+
92
+ | Option | Values | |
93
+ | --- | --- | --- |
94
+ | `headings` | `'keep'` (default), `'strong'` | `'strong'`: every heading becomes a paragraph of strong text |
95
+ | `images` | `'keep'` (default), `'link'` | `'link'`: every image becomes a link to it, with the alt text as its text |
96
+ | `html` | `'text'` (default), `'drop'`, `'allow'` | raw HTML is never markup. `'text'` shows it as written, `'drop'` removes it, `'allow'` keeps `<kbd>`, `<sub>`, `<sup>`, `<mark>` and `<details>` with `<summary>`, with only `open` of their attributes, and shows the rest as written |
97
+ | `base` | a folder from the project root, `'/content/posts/'` | relative image and link URLs become root paths under it, so the image pipeline finds an image next to the markdown file. Links to other `.md` files, `#fragments`, `?queries` and absolute URLs stay as written |
98
+
99
+ For readers' content (comments, reviews):
100
+
101
+ ```html
102
+ data-sn-let="{ doc: md.parse(c.body, { headings: 'strong', images: 'link', html: 'text' }) }"
103
+ ```
104
+
105
+ An unknown value is an error that lists the values (`md.parse: \`html\` is 'drop', 'text', 'allow'`).
106
+
107
+ ## `md.headings(doc)` and `md.text(node)`
108
+
109
+ ```html
110
+ <nav><template data-sn-for="h in md.headings(doc)">
111
+ <a data-sn-attr="{ href: '#' + h.id }" data-sn-text="h.text"></a>
112
+ </template></nav>
113
+ <p class="summary" data-sn-text="md.text(doc).slice(0, 160)"></p>
114
+ <p class="time" data-sn-text="Math.ceil(md.text(doc).split(/\s+/).length / 230) + ' min read'"></p>
115
+ ```
116
+
117
+ - `md.headings(doc)` lists the headings at any depth (in quotes and lists too) as `{ depth, id, text }`.
118
+ `id` is the heading's anchor in `<md-doc>`: `md-` and a slug of its text, as GitHub writes slugs
119
+ (`## Getting started` is `id="md-getting-started"`), with `-1`, `-2` for repeats. The prefix is there
120
+ because an id written from data could shadow a global another script reads (DOM clobbering, sinter's
121
+ `SN503`). A heading node carries the slug (`node.slug`), so a heading fill writes the same id.
122
+ - `md.text(node)` is the plain text of a document, a node or a list of nodes: inline content run
123
+ together, blocks separated by a blank line, an image as its alt text. For a description or a reading
124
+ time.
125
+
126
+ Both are pure: over a file they run at build time. In the browser they walk the tree at each read,
127
+ which is cheap (about 0.1–0.2 ms on a 47.5 kB article).
128
+
129
+ ### The tree is kept and frozen
130
+
131
+ A let or a prop is evaluated where it is read, and `<md-doc>` reads its `doc` at every node, so
132
+ `md.parse` keeps the trees it returns: the same source and options give the same tree, parsed once,
133
+ whichever let, prop or row asks. Equal options are one policy (`{}` and `{ html: 'text' }`). The tree
134
+ is frozen, at every depth, and shared: to change one, change a copy (`structuredClone(doc)`). About
135
+ 8 MiB of trees are kept, the least recently used dropped first.
136
+
137
+ ## `<md-doc>` and `<md-inline>`
138
+
139
+ | | Renders | Root |
140
+ | --- | --- | --- |
141
+ | `<md-doc data-sn-prop="{ doc }">` | the blocks of a document | `<div class="md">` |
142
+ | `<md-inline data-sn-prop="{ doc }">` | one line: the content of the paragraphs and headings, without their elements, with a space between two of them (a title, a label); other blocks are left out | `<span class="md">` |
143
+
144
+ - `doc` is optional: with none, the root is empty. Its root is always there, so the tag may carry a
145
+ `class`, attributes and handlers.
146
+ - `<md-inline>` is phrasing content, a `<span>` with only phrasing content inside, so it is valid in
147
+ a heading, a label, a link or a paragraph: `<h1><md-inline data-sn-prop="{ doc: md.parse(post.title)
148
+ }"></md-inline></h1>`. Parse a title with the options that fit a line; a list or a code block in it
149
+ is not rendered.
150
+ - The HTML is what a markdown renderer writes, with no wrapper of its own but one: `<h2 id="md-…">`,
151
+ `<p>`, `<em>`, `<a href title>`, `<pre><code class="language-ts">`, `<ul>`/`<ol start>`, a task's
152
+ `<input type="checkbox" disabled>` in an `<li class="task-list-item">`, `<blockquote>`, `<hr>`, and a
153
+ table in a `<div class="md-table">` (the one wrapper, see the `table` slot).
154
+ - Lists and branches are marked by comments in the page, as everywhere in sinter, so prose CSS sees
155
+ plain HTML: `.md h2 + p`, `.md li:first-child` and `.md > * + *` match as they would in static HTML.
156
+ - A link's and an image's URL are attribute bindings, so sinter refuses `javascript:` and other unsafe
157
+ schemes, in the browser and at build time, whatever the parser let through.
158
+ - An image is a plain `<img>`. From a file it is a local image, optimized as any image in a page
159
+ (`<picture>`, `srcset`, `width` and `height`). From an API it is written as given, and is not sent
160
+ through the app's resizing service (`images.remote`): readers' content may name any image. Fill the
161
+ `image` slot to resize it.
162
+
163
+ ## Slots
164
+
165
+ `<md-doc>` declares one slot per kind of node an app is likely to change; `<md-inline>` declares the
166
+ ones it can render, `link`, `image` and `inlineCode`. A fill changes that kind of node wherever it is
167
+ in the tree, in a list item, a quote or a table cell. Each passes the node as `$slot.node`, and a
168
+ `<slot>` inside the fill is the default element's children:
169
+
170
+ | Slot | `$slot.node` | Default |
171
+ | --- | --- | --- |
172
+ | `heading` | `Heading` (`depth`, `slug`, `children`) | `<h1 id="md-…">`…`<h6>` |
173
+ | `link` | `Link` (`url`, `title`, `children`) | `<a href title>` |
174
+ | `image` | `Image` (`url`, `alt`, `title`) | `<img src alt title>` |
175
+ | `code` | `Code` (`lang`, `meta`, `value`) | `<pre><code class="language-…">` |
176
+ | `inlineCode` | `InlineCode` (`value`) | `<code>` |
177
+ | `blockquote` | `Blockquote` (`children`) | `<blockquote>` |
178
+ | `table` | `Table` (`align`, `children`) | `<div class="md-table"><table>…</table></div>` |
179
+
180
+ ```html
181
+ <md-doc data-sn-prop="{ doc }">
182
+ <!-- readers' links -->
183
+ <a slot="link" rel="nofollow ugc" data-sn-attr="{ href: $slot.node.url }"><slot></slot></a>
184
+ <!-- a heading with a link to itself: an if chain over the depth -->
185
+ <template slot="heading" data-sn-if="$slot.node.depth === 1"><h1 data-sn-attr="{ id: 'md-' + $slot.node.slug }"><slot></slot></h1></template>
186
+ <template data-sn-else><h2 data-sn-attr="{ id: 'md-' + $slot.node.slug }"><slot></slot> <a data-sn-attr="{ href: '#md-' + $slot.node.slug }">#</a></h2></template>
187
+ <!-- a table that scrolls: the fill places the whole table -->
188
+ <div slot="table" class="scroll"><slot></slot></div>
189
+ <!-- a code block with a caption -->
190
+ <figure slot="code"><pre><code data-sn-text="$slot.node.value"></code></pre><figcaption data-sn-text="$slot.node.lang"></figcaption></figure>
191
+ </md-doc>
192
+ ```
193
+
194
+ - The table's default is a wrapper around the `<table>` because the HTML parser moves a `<slot>`
195
+ written inside a `<table>` out of it: a fill cannot write `<table><slot></slot></table>`, so it
196
+ places the whole table, or renders its own from `$slot.node`.
197
+ - A fill is the page's markup: it reads the page's state and helpers, and its handlers write the page's
198
+ state. Over a file, a fill that reads only constants is expanded at build time with the rest of the
199
+ tree, the ones above included. Two kinds render in the browser instead: a fill that holds a
200
+ component with slots of its own (another `<md-doc>`), and one your wrapper passes on with
201
+ `<slot name="link" slot="link">`; on a static page, `SN322` names the fill and why. A code block's fill can highlight at build time with a helper of yours over `$slot.node.value`.
202
+ - To give every page the same looks, write a wrapper component whose root is `<md-doc>` with your
203
+ fills, and use it instead
204
+ ([app-wide looks](https://github.com/tiaforge/sinter/blob/main/docs/components.md#tree-slots)).
205
+ Name the package's types in your own declarations through `src/sinter.types.ts`.
206
+
207
+ ## Styles
208
+
209
+ The components carry no CSS. Style the tree under `.md`, which both roots have:
210
+
211
+ ```css
212
+ .md > * + * { margin-block-start: 1em; }
213
+ .md .task-list-item { list-style: none; }
214
+ .md .md-table { overflow-x: auto; }
215
+ ```
216
+
217
+ ## Performance
218
+
219
+ The 300-block article of sinter's markdown measurements (47.5 kB of markdown, every node type) from an API, in
220
+ headless Chromium on one machine, served gzipped, one fresh context per run, the three pages interleaved
221
+ (2026-11-17, [bench/markdown](https://github.com/tiaforge/sinter/tree/main/bench/markdown)). Over loopback, median of
222
+ 21; on slow 4G (150 ms round trip, 1.6 Mbit/s) with the CPU 4× slower, the medians of two sets of 7. The comparison is
223
+ the same markdown through marked and DOMPurify into `innerHTML`, without Trusted Types (`innerHTML` with a string
224
+ needs a policy), as the RealWorld example rendered its article body until it used this library. The first two rows
225
+ read the same response; the third reads another one, the tree, which only an API you control can send.
226
+
227
+ | Page | API response | LCP, loopback | LCP, slow 4G | Script | Scripts (gzip) | Response (gzip) | Comments |
228
+ | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: |
229
+ | markdown from the API, `md.parse` in the page | the markdown | 164 ms | 1,160–1,180 ms | 73 ms | 45.8 kB | 11.3 kB | 3,088 |
230
+ | marked + DOMPurify | the markdown | 172 ms | 1,208–1,220 ms | 60 ms | 36.9 kB | 11.3 kB | 2 |
231
+ | tree from the API | the tree (`md.parse` run beforehand, in Node) | 128 ms | 908–928 ms | 39 ms | 20.8 kB | 14.0 kB | 3,088 |
232
+
233
+ - Every page renders the same 1,365 elements (marked + DOMPurify 1,370: marked writes newlines between blocks as
234
+ text).
235
+ - For the same API, sinter-markdown and marked + DOMPurify are level on LCP over loopback, and sinter-markdown is
236
+ about 40 ms ahead on slow 4G.
237
+ - Before the parser was trimmed (the same day: markdown-it whole, linkify-it, the entity table unpacked), the first
238
+ row loaded 58.6 kB of scripts and reached LCP at 164 ms over loopback and 1,224–1,276 ms on slow 4G.
239
+ - Scripts are every script the page loads, sinter's runtime included; script time is Chromium's for the whole page
240
+ load (`ScriptDuration`). marked + DOMPurify's leaves out the browser's own parsing of the HTML string, which is in
241
+ its LCP.
242
+ - The tree row is not that comparison: its parse ran before the measurement (as for an API that stores the tree),
243
+ and its cost on a server that parses per request is not measured. What it shows is what the parse costs the
244
+ page: the parser's download and run, then the tree. The tree is about 25 % larger on the wire than its markdown.
245
+ - The comments are the anchors of lists and branches, which keep the page live: a change to the source renders
246
+ again what changed. A row or branch that is only another branch, or only a text, has none of its own.
247
+ - From a file (`file:`), the article is HTML at build time and ships no JavaScript: LCP 56–60 ms in an earlier
248
+ session of the same machine.
249
+
250
+ ## Limits
251
+
252
+ - A raw HTML block is CommonMark's: a line that starts with a tag (`<div>`, `<script>`) makes the whole
253
+ block raw, so the markdown after it on those lines is shown as written too.
254
+ - `<details>` under `html: 'allow'` is kept when its start and end are blocks of their own between
255
+ the same siblings (`<details>` … blank line … blocks … blank line … `</details>`); otherwise it is
256
+ shown as written.
257
+ - Links between markdown files stay as written; a page per markdown file is not part of sinter yet.
258
+ - Parsing a stream parses the whole source again for each chunk.
@@ -0,0 +1,28 @@
1
+ <!--
2
+ An article and its comments from an API, on one page (docs/markdown.md).
3
+ The article is the team's markdown: headings with anchors, a table of contents from the same tree.
4
+ The comments are readers' markdown, under the user-content policy: no headings, no images, raw HTML
5
+ shown as written, and links marked as user content by a fill.
6
+ -->
7
+ <sn-resource name="post" src="/api/post"></sn-resource>
8
+ <!-- keyed: a comment added later (upsert, a server event) joins the list instead of replacing it -->
9
+ <sn-resource name="comments" src="/api/post/comments" key="id"></sn-resource>
10
+
11
+ <article id="post" data-sn-let="{ doc: md.parse(post?.body) }">
12
+ <h1><md-inline data-sn-prop="{ doc: md.parse(post?.title) }"></md-inline></h1>
13
+ <nav aria-label="Contents">
14
+ <ol>
15
+ <template data-sn-for="h in md.headings(doc)"><li><a data-sn-attr="{ href: '#' + h.id }" data-sn-text="h.text"></a></li></template>
16
+ </ol>
17
+ </nav>
18
+ <md-doc id="body" data-sn-prop="{ doc }"></md-doc>
19
+ </article>
20
+
21
+ <section id="comments" aria-label="Comments">
22
+ <template data-sn-for="c in comments" data-sn-key="c.id">
23
+ <article class="comment" data-sn-let="{ doc: md.parse(c.body, { headings: 'strong', images: 'link', html: 'text' }) }">
24
+ <h3 data-sn-text="c.author"></h3>
25
+ <md-doc data-sn-prop="{ doc }"><a slot="link" rel="nofollow ugc" data-sn-attr="{ href: $slot.node.url }"><slot></slot></a></md-doc>
26
+ </article>
27
+ </template>
28
+ </section>
package/llms.txt ADDED
@@ -0,0 +1,44 @@
1
+ # @tiaforge-ui/sinter-markdown
2
+
3
+ > Markdown for sinter: md.parse(source, options) returns a tree (mdast: CommonMark and GFM tables, task lists, strikethrough, autolinks), <md-doc> and <md-inline> render it, slots change how a kind of node renders. A file's markdown is plain HTML at build time; an API's is parsed in the browser.
4
+
5
+ ## Setup
6
+
7
+ - vite.config: `sinter({ components: ['@tiaforge-ui/sinter-markdown'] })`; to load the parser on demand, also `lazy: ['@tiaforge-ui/sinter-markdown']`.
8
+ - src/sinter.helpers.ts: `export * as md from '@tiaforge-ui/sinter-markdown';`
9
+ - src/sinter.types.ts: `export type { Root, Heading, Link, Image, Code, Table, TocEntry } from '@tiaforge-ui/sinter-markdown';`
10
+
11
+ ## Pages
12
+
13
+ - From a file (static, no JavaScript): `<sn-resource name="post" src="file:./post.md"></sn-resource><main data-sn-let="{ doc: md.parse(post, { base: '/posts/' }) }"><md-doc data-sn-prop="{ doc }"></md-doc></main>`. `base` (a folder from the project root) makes relative image and link URLs root paths, so local images are optimized.
14
+ - From an API: `<article data-sn-let="{ doc: md.parse(post?.body) }"><md-doc data-sn-prop="{ doc }"></md-doc></article>`. md.parse keeps its trees (frozen, shared): one parse per source and options, whatever reads it. With the parser lazy, `doc` is undefined until it loads; <md-doc> renders an empty root meanwhile.
15
+ - Readers' content: `md.parse(c.body, { headings: 'strong', images: 'link', html: 'text' })`, and a link fill with `rel="nofollow ugc"`.
16
+ - One line (a title, a label): `<h1><md-inline data-sn-prop="{ doc: md.parse(post.title) }"></md-inline></h1>`: a `<span class="md">` with the paragraphs' and headings' content (phrasing content only; other blocks left out).
17
+
18
+ ## md.parse options
19
+
20
+ - `headings`: 'keep' (default) | 'strong' (every heading a paragraph of strong text)
21
+ - `images`: 'keep' (default) | 'link' (every image a link to it)
22
+ - `html`: 'text' (default: raw HTML shown as written) | 'drop' | 'allow' (kbd, sub, sup, mark, details/summary; only `open`)
23
+ - `base`: '/folder/' (relative URLs become root paths; .md links, #fragments and absolute URLs stay)
24
+
25
+ ## Helpers that read a tree
26
+
27
+ - `md.headings(doc)`: `{ depth, id, text }[]`; `id` is the heading's anchor in <md-doc>, `md-` + slug (`#md-getting-started`).
28
+ - `md.text(node)`: plain text, blocks separated by a blank line.
29
+ - Both import no parser: ordinary helpers, early and folded at build time, also with the parser lazy.
30
+
31
+ ## Slots (on <md-doc>; <md-inline> has link, image and inlineCode), each with `$slot.node`
32
+
33
+ - `heading` (Heading: depth, slug, children; anchor id 'md-' + slug), `link` (url, title), `image` (url, alt, title), `code` (lang, meta, value), `inlineCode` (value), `blockquote`, `table` (default: `<div class="md-table"><table>`; a fill places the whole table with `<slot></slot>`).
34
+ - `<slot></slot>` in a fill is the default element's children: `<a slot="link" rel="nofollow ugc" data-sn-attr="{ href: $slot.node.url }"><slot></slot></a>`.
35
+ - A heading fill picks its level with a chain: `<template slot="heading" data-sn-if="$slot.node.depth === 1">…</template><template data-sn-else>…</template>`.
36
+ - App-wide looks: a wrapper component whose root is <md-doc> with the fills.
37
+
38
+ ## Output
39
+
40
+ - Plain HTML under `<div class="md">` (`<span class="md">` for md-inline): h1–h6 with ids, p, em, strong, del, code, pre > code.language-x, ul, ol[start], li.task-list-item with a disabled checkbox, blockquote, hr, img, a, table in div.md-table. No CSS: style `.md …`.
41
+ - URLs are attribute bindings: javascript: and other unsafe schemes are refused. An image from an API is a plain <img>, not sent through the app's resizing service.
42
+ - Lists and branches are marked by comments: keep HTML comments (no comment-stripping minifier).
43
+
44
+ Docs: docs/markdown.md in the package. Recipe: docs/recipes/article-with-comments.html.