diff --git a/docs/guide/plugins.md b/docs/guide/plugins.md index cb9b5b4..cb4ff30 100644 --- a/docs/guide/plugins.md +++ b/docs/guide/plugins.md @@ -66,9 +66,9 @@ Release read the `MarkdownExit` class [properties](/reference/api/Class.Markdown ### Supporting the Core Entry -Apps may import from [`markdown-exit/core`](/guide/quick-start.html#core-entry) to leave out linkify-it. To keep your plugin compatible: +Apps may import from [`markdown-exit/core`](/guide/quick-start.html#core-entry) to leave out linkify-it and the named character reference table. To keep your plugin compatible: -- Use `import type` for types. If your plugin needs runtime values such as `Token`, import them from `markdown-exit/core`, which shares the same classes as `markdown-exit`. Importing `markdown-exit` at runtime adds linkify-it to the bundle of every app that uses your plugin. +- Use `import type` for types. If your plugin needs runtime values such as `Token`, import them from `markdown-exit/core`, which shares the same classes as `markdown-exit`. Importing `markdown-exit` at runtime adds linkify-it and the named character reference table to the bundle of every app that uses your plugin. - `md.linkify` is `undefined` in the core entry until the app assigns a linkify-it instance. If your plugin accesses `md.linkify`, guard against that or document that the plugin requires linkify-it. ### Async Render Rules diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md index fceee5b..f523d1a 100644 --- a/docs/guide/quick-start.md +++ b/docs/guide/quick-start.md @@ -121,7 +121,7 @@ const md = new MarkdownExit() ## Core Entry -`markdown-exit/core` exposes the same API as `markdown-exit`, but leaves out [linkify-it](https://github.com/markdown-it/linkify-it), the library behind the [`linkify`](/reference/api/Interface.MarkdownExitOptions.html#linkify) option. If you never enable `linkify`, import from `markdown-exit/core` to get a smaller bundle: +`markdown-exit/core` exposes the same API as `markdown-exit`, but leaves out two things: [linkify-it](https://github.com/markdown-it/linkify-it), the library behind the [`linkify`](/reference/api/Interface.MarkdownExitOptions.html#linkify) option, and the table of named character references such as `©`. Import from `markdown-exit/core` to get a smaller bundle: ```ts import { createMarkdownExit } from 'markdown-exit/core' @@ -140,6 +140,22 @@ const md = createMarkdownExit({ linkify: true }) md.linkify = new LinkifyIt() ``` +The core entry also has no table for named character references. Numeric ones such as `©` always decode, but parsing a named one such as `©` throws until you set the table from [`character-entities`](https://github.com/wooorm/character-entities). The table is about 12 KiB gzip, so you can load it only when a document contains `&` followed by a letter: + +```ts +import { createMarkdownExit, setNamedEntities } from 'markdown-exit/core' + +const md = createMarkdownExit() + +async function render(src: string) { + if (/&[a-z]/i.test(src)) { + const { characterEntities } = await import('character-entities') + setNamedEntities(characterEntities) + } + return md.render(src) +} +``` + > [!WARNING] > - Plugins that access `md.linkify` (e.g. `md.linkify.set(...)`) throw in the core entry unless you assign a linkify-it instance before calling `md.use()`. -> - If any module in your app imports `markdown-exit` instead of `markdown-exit/core`, linkify-it is bundled anyway, and instances created from `markdown-exit/core` get a linkify-it instance too. +> - If any module in your app imports `markdown-exit` instead of `markdown-exit/core`, linkify-it and the named character reference table are bundled anyway, instances created from `markdown-exit/core` get a linkify-it instance too, and the table is set for every instance. diff --git a/packages/markdown-exit/src/common/entities.ts b/packages/markdown-exit/src/common/entities.ts index 4ce98de..d661811 100644 --- a/packages/markdown-exit/src/common/entities.ts +++ b/packages/markdown-exit/src/common/entities.ts @@ -1,7 +1,19 @@ -import { characterEntities } from 'character-entities' - const own = Object.prototype.hasOwnProperty +let entities: Record | undefined + +/** + * Sets the table of named character references, such as `©`, that the + * parser decodes. `markdown-exit` sets `character-entities` when it's + * imported; `markdown-exit/core` leaves it to the app, so a bundle can load the + * table only when a document needs it. + */ +export function setNamedEntities(table: Record): void { + entities = table +} + export function decodeNamedEntity(name: string): string | undefined { - return own.call(characterEntities, name) ? characterEntities[name] : undefined + if (!entities) + throw new Error('markdown-exit/core does not include the named entity table. Call `setNamedEntities(characterEntities)` with the table from `character-entities` before parsing `&name;` references.') + return own.call(entities, name) ? entities[name] : undefined } diff --git a/packages/markdown-exit/src/index.core.ts b/packages/markdown-exit/src/index.core.ts index 8cef5ae..cdedab3 100644 --- a/packages/markdown-exit/src/index.core.ts +++ b/packages/markdown-exit/src/index.core.ts @@ -2,6 +2,8 @@ import type { createMarkdownExit } from './core' import { callable } from './common/utils' import { MarkdownExit } from './core' +export { setNamedEntities } from './common/entities' + export * from './core' export * from './parser' export * from './renderer' diff --git a/packages/markdown-exit/src/index.ts b/packages/markdown-exit/src/index.ts index d5abee2..52ff91c 100644 --- a/packages/markdown-exit/src/index.ts +++ b/packages/markdown-exit/src/index.ts @@ -1,7 +1,10 @@ +import { characterEntities } from 'character-entities' import { LinkifyIt } from 'linkify-it' +import { setNamedEntities } from './common/entities' import { setLinkifyFactory } from './parser/linkify-it' setLinkifyFactory(() => new LinkifyIt()) +setNamedEntities(characterEntities) export * from './index.core' export { default } from './index.core' diff --git a/packages/markdown-exit/tests/core-entry.test.ts b/packages/markdown-exit/tests/core-entry.test.ts index 91aef68..e95ce64 100644 --- a/packages/markdown-exit/tests/core-entry.test.ts +++ b/packages/markdown-exit/tests/core-entry.test.ts @@ -1,9 +1,10 @@ import type { Rollup } from 'vite' import { fileURLToPath } from 'node:url' +import { characterEntities } from 'character-entities' import { LinkifyIt } from 'linkify-it' import { build } from 'vite' import { assert, describe, it } from 'vitest' -import MarkdownExit from '../src/index.core' +import MarkdownExit, { setNamedEntities } from '../src/index.core' async function bundleImports(entry: string): Promise { const result = await build({ @@ -24,6 +25,11 @@ describe('markdown-exit/core', () => { assert.notInclude(await bundleImports('../src/index.core.ts'), 'linkify-it') }) + it('does not bundle the named entity table', async () => { + assert.include(await bundleImports('../src/index.ts'), 'character-entities') + assert.notInclude(await bundleImports('../src/index.core.ts'), 'character-entities') + }) + it('renders without linkify-it', () => { const md = MarkdownExit() @@ -38,4 +44,15 @@ describe('markdown-exit/core', () => { md.linkify = new LinkifyIt() assert.strictEqual(md.render('https://example.com'), '

https://example.com

\n') }) + + it('needs the named entity table to decode `&name;`', () => { + const md = MarkdownExit() + + assert.strictEqual(md.render('AT&T © © & co'), '

AT&T © © & co

\n') + assert.throws(() => md.render('©'), /setNamedEntities/) + assert.throws(() => md.render('[a](/b "©")'), /setNamedEntities/) + + setNamedEntities(characterEntities) + assert.strictEqual(md.render('© &nosuch; [a](/b "©")'), '

© &nosuch; a

\n') + }) })