@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.
- package/README.md +305 -2
- package/docs/markdown.md +258 -0
- package/docs/recipes/article-with-comments.html +28 -0
- package/llms.txt +44 -0
- package/package.json +65 -4
- package/sinter/components/internal/md-block.html +7 -0
- package/sinter/components/internal/md-blockquote.html +3 -0
- package/sinter/components/internal/md-break.html +3 -0
- package/sinter/components/internal/md-code.html +4 -0
- package/sinter/components/internal/md-delete.html +3 -0
- package/sinter/components/internal/md-details.html +4 -0
- package/sinter/components/internal/md-emphasis.html +3 -0
- package/sinter/components/internal/md-heading.html +4 -0
- package/sinter/components/internal/md-image.html +9 -0
- package/sinter/components/internal/md-inline-code.html +3 -0
- package/sinter/components/internal/md-kbd.html +3 -0
- package/sinter/components/internal/md-link.html +4 -0
- package/sinter/components/internal/md-list-item.html +4 -0
- package/sinter/components/internal/md-list.html +4 -0
- package/sinter/components/internal/md-mark.html +3 -0
- package/sinter/components/internal/md-paragraph.html +3 -0
- package/sinter/components/internal/md-phrasing.html +9 -0
- package/sinter/components/internal/md-strong.html +3 -0
- package/sinter/components/internal/md-sub.html +3 -0
- package/sinter/components/internal/md-sup.html +3 -0
- package/sinter/components/internal/md-table.html +9 -0
- package/sinter/components/internal/md-thematic-break.html +3 -0
- package/sinter/components/md-doc.html +10 -0
- package/sinter/components/md-inline.html +11 -0
- package/sinter/index.ts +5 -0
- package/sinter/parse.ts +270 -0
- package/sinter/parser.d.ts +19 -0
- package/sinter/parser.js +2872 -0
- package/sinter/sinter.helpers.ts +10 -0
- package/sinter/sinter.types.ts +209 -0
- package/sinter/tree.ts +61 -0
package/README.md
CHANGED
|
@@ -1,3 +1,306 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @tiaforge-ui/sinter-markdown
|
|
2
2
|
|
|
3
|
-
|
|
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
|
package/docs/markdown.md
ADDED
|
@@ -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 (`&` 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.
|