Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/guide/plugins.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 18 additions & 2 deletions docs/guide/quick-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand All @@ -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.
18 changes: 15 additions & 3 deletions packages/markdown-exit/src/common/entities.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,19 @@
import { characterEntities } from 'character-entities'

const own = Object.prototype.hasOwnProperty

let entities: Record<string, string> | undefined

/**
* Sets the table of named character references, such as `&copy;`, 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<string, string>): 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
}
2 changes: 2 additions & 0 deletions packages/markdown-exit/src/index.core.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
3 changes: 3 additions & 0 deletions packages/markdown-exit/src/index.ts
Original file line number Diff line number Diff line change
@@ -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'
19 changes: 18 additions & 1 deletion packages/markdown-exit/tests/core-entry.test.ts
Original file line number Diff line number Diff line change
@@ -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<string[]> {
const result = await build({
Expand All @@ -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()

Expand All @@ -38,4 +44,15 @@ describe('markdown-exit/core', () => {
md.linkify = new LinkifyIt()
assert.strictEqual(md.render('https://example.com'), '<p><a href="https://example.com">https://example.com</a></p>\n')
})

it('needs the named entity table to decode `&name;`', () => {
const md = MarkdownExit()

assert.strictEqual(md.render('AT&T &#169; &#xA9; & co'), '<p>AT&amp;T © © &amp; co</p>\n')
assert.throws(() => md.render('&copy;'), /setNamedEntities/)
assert.throws(() => md.render('[a](/b "&copy;")'), /setNamedEntities/)

setNamedEntities(characterEntities)
assert.strictEqual(md.render('&copy; &nosuch; [a](/b "&copy;")'), '<p>© &amp;nosuch; <a href="/b" title="©">a</a></p>\n')
})
})
Loading