From e31215bf35838f16b9a53014b17ebd206ffed754 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 10:06:53 +0100 Subject: [PATCH 01/15] perf(core): update markdown-exit to 2.1 and keep one entity table in bundles MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Import from markdown-exit/core and load linkify-it on the first parse with linkify on. Decode entities with character-entities, the table markdown-exit already uses, instead of entities. Keep linkify-it 5's fuzzyLink and urlAuth behavior. Attribute values keep a legacy reference literal before `=` or an alphanumeric, as browsers do, so `¬in&` stays as written where entities 7 decoded it to `Β¬in&`. --- AGENTS.md | 2 + packages/comark/package.json | 5 +- packages/comark/src/internal/entities.ts | 113 ++++++++++++++++++ packages/comark/src/internal/parse/indent.ts | 2 +- .../comark/src/internal/parse/tree-utils.ts | 2 +- packages/comark/src/internal/parse/tree.ts | 2 +- packages/comark/src/internal/parse/utils.ts | 2 +- packages/comark/src/parse.ts | 15 ++- packages/comark/src/plugins/attributes.ts | 4 +- packages/comark/src/plugins/binding.ts | 2 +- packages/comark/src/plugins/components.ts | 2 +- packages/comark/src/plugins/html.ts | 2 +- packages/comark/src/plugins/math.ts | 2 +- packages/comark/src/plugins/mermaid.ts | 2 +- packages/comark/src/types.ts | 4 +- packages/comark/test/linkify.test.ts | 45 +++++++ .../parse/html-attribute-references.test.ts | 16 +++ pnpm-lock.yaml | 45 +++++-- pnpm-workspace.yaml | 9 +- 19 files changed, 250 insertions(+), 26 deletions(-) create mode 100644 packages/comark/src/internal/entities.ts create mode 100644 packages/comark/test/linkify.test.ts create mode 100644 packages/comark/test/parse/html-attribute-references.test.ts diff --git a/AGENTS.md b/AGENTS.md index f188c1871..0e622bb63 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -865,6 +865,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup and the example-app wor 1. Token processing is in `packages/comark/src/internal/parse/token-processor.ts` 2. Test with `packages/comark/test/index.test.ts` (loads the `SPEC/` fixtures; `SPEC=SPEC/COMARK/foo.md pnpm vitest run test/index.test.ts` runs one) 3. Check streaming still works with `packages/comark/test/streaming.test.ts` +4. Import from `markdown-exit/core`, never `markdown-exit`: the root entry pulls in linkify-it, which `parse.ts` loads lazily only for parsers with `linkify` on +5. Decode attribute values with `decodeHTMLAttribute` from `src/internal/entities.ts`, not `entities`: it reads the `character-entities` table markdown-exit already ships, so bundles hold one table ### Adding component features diff --git a/packages/comark/package.json b/packages/comark/package.json index 70e184f51..8864a64e9 100644 --- a/packages/comark/package.json +++ b/packages/comark/package.json @@ -69,14 +69,17 @@ "release:dry": "release-it --dry-run" }, "dependencies": { - "entities": "catalog:", + "character-entities": "catalog:", + "character-entities-legacy": "catalog:", "js-yaml": "catalog:", + "linkify-it": "catalog:", "markdown-exit": "catalog:" }, "devDependencies": { "@json-render/core": "catalog:", "@shikijs/twoslash": "catalog:", "@types/markdown-it": "catalog:", + "entities": "catalog:", "github-slugger": "catalog:", "hast-util-to-string": "catalog:", "minimark": "catalog:", diff --git a/packages/comark/src/internal/entities.ts b/packages/comark/src/internal/entities.ts new file mode 100644 index 000000000..1415c65e5 --- /dev/null +++ b/packages/comark/src/internal/entities.ts @@ -0,0 +1,113 @@ +import { characterEntities } from 'character-entities' +import { characterEntitiesLegacy } from 'character-entities-legacy' + +// markdown-exit decodes with `character-entities`, so reusing it keeps a single +// entity table in bundles instead of shipping a second one from `entities`. + +const own = Object.prototype.hasOwnProperty +const legacy = new Set(characterEntitiesLegacy) + +// HTML maps C1 control code points to their windows-1252 characters. +const C1: Record = { + 0x80: 0x20ac, + 0x82: 0x201a, + 0x83: 0x0192, + 0x84: 0x201e, + 0x85: 0x2026, + 0x86: 0x2020, + 0x87: 0x2021, + 0x88: 0x02c6, + 0x89: 0x2030, + 0x8a: 0x0160, + 0x8b: 0x2039, + 0x8c: 0x0152, + 0x8e: 0x017d, + 0x91: 0x2018, + 0x92: 0x2019, + 0x93: 0x201c, + 0x94: 0x201d, + 0x95: 0x2022, + 0x96: 0x2013, + 0x97: 0x2014, + 0x98: 0x02dc, + 0x99: 0x2122, + 0x9a: 0x0161, + 0x9b: 0x203a, + 0x9c: 0x0153, + 0x9e: 0x017e, + 0x9f: 0x0178, +} + +function isDigit(code: number): boolean { + return code >= 48 && code <= 57 +} + +function isHexDigit(code: number): boolean { + return isDigit(code) || (code >= 65 && code <= 70) || (code >= 97 && code <= 102) +} + +function isAlphanumeric(code: number): boolean { + return isDigit(code) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122) +} + +function fromNumericReference(value: number): string { + if (value === 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) return 'οΏ½' + return String.fromCodePoint(C1[value] ?? value) +} + +/** + * Decode character references in an attribute value the way browsers do: + * numeric references, named references, and the legacy names (`&`, `<`, + * `©`, …) allowed without a trailing semicolon, unless `=` or an + * alphanumeric follows them (`?a=1©=2` stays literal). + */ +export function decodeHTMLAttribute(input: string): string { + let amp = input.indexOf('&') + if (amp === -1) return input + + let out = '' + let last = 0 + const length = input.length + + while (amp !== -1) { + let end = amp + 1 + let decoded: string | undefined + + if (input.charCodeAt(end) === 35 /* # */) { + end++ + const hex = (input.charCodeAt(end) | 0x20) === 120 /* x */ + if (hex) end++ + const start = end + const isValid = hex ? isHexDigit : isDigit + let value = 0 + while (end < length && isValid(input.charCodeAt(end))) { + // Clamp so overlong references stay out of range instead of overflowing. + value = Math.min(value * (hex ? 16 : 10) + Number.parseInt(input[end], 16), 0x110000) + end++ + } + if (end > start) { + decoded = fromNumericReference(value) + if (input.charCodeAt(end) === 59 /* ; */) end++ + } + } else { + while (end < length && isAlphanumeric(input.charCodeAt(end))) end++ + const name = input.slice(amp + 1, end) + const next = input.charCodeAt(end) + if (next === 59 /* ; */ && own.call(characterEntities, name)) { + decoded = characterEntities[name] + end++ + } else if (next !== 61 /* = */ && legacy.has(name)) { + // Any shorter legacy prefix of `name` is followed by an alphanumeric, which keeps it literal. + decoded = characterEntities[name] + } + } + + if (decoded !== undefined) { + out += input.slice(last, amp) + decoded + last = end + } + amp = input.indexOf('&', decoded === undefined ? amp + 1 : end) + } + + return out + input.slice(last) +} diff --git a/packages/comark/src/internal/parse/indent.ts b/packages/comark/src/internal/parse/indent.ts index a8818ab2b..76fca3068 100644 --- a/packages/comark/src/internal/parse/indent.ts +++ b/packages/comark/src/internal/parse/indent.ts @@ -5,7 +5,7 @@ * These helpers shift the region left instead. */ -import type { StateBlock } from 'markdown-exit' +import type { StateBlock } from 'markdown-exit/core' /** * Remove up to `columns` columns of indentation from `line`, in place. diff --git a/packages/comark/src/internal/parse/tree-utils.ts b/packages/comark/src/internal/parse/tree-utils.ts index 0f9c344a7..6c4700d55 100644 --- a/packages/comark/src/internal/parse/tree-utils.ts +++ b/packages/comark/src/internal/parse/tree-utils.ts @@ -1,5 +1,5 @@ import type { Node } from 'comark' -import type { Token } from 'markdown-exit' +import type { Token } from 'markdown-exit/core' // Upper bound for expanded highlight ranges in a fence info string. const MAX_HIGHLIGHT_LINES = 1_000 diff --git a/packages/comark/src/internal/parse/tree.ts b/packages/comark/src/internal/parse/tree.ts index 62640668d..b636d5568 100644 --- a/packages/comark/src/internal/parse/tree.ts +++ b/packages/comark/src/internal/parse/tree.ts @@ -1,4 +1,4 @@ -import { Token } from 'markdown-exit' +import { Token } from 'markdown-exit/core' import type { CommentNode, ElementNode, ElementNodeAttributes, HeadingIdsOption, Node } from 'comark' import { extractAttributes, mergeAdjacentTextNodes, parseCodeblockInfo, processAttributes } from './tree-utils.ts' import { createHeadingIdTracker, nextHeadingId, reserveHeadingId, type HeadingIdTracker } from '../heading-id.ts' diff --git a/packages/comark/src/internal/parse/utils.ts b/packages/comark/src/internal/parse/utils.ts index 098016d54..377bcb3b1 100644 --- a/packages/comark/src/internal/parse/utils.ts +++ b/packages/comark/src/internal/parse/utils.ts @@ -1,6 +1,6 @@ import type { Node, ElementNode, ElementNodeAttributes, MarkdownDocument } from 'comark' -import { decodeHTMLAttribute } from 'entities' import { isHtmlVoidElement, TREE_WALK_MAX_DEPTH } from 'comark/utils' +import { decodeHTMLAttribute } from '../entities.ts' /** Space, tab, line feed, form feed or carriage return. Defined per file so it stays inlinable on hot paths. */ function isSpaceCode(c: number): boolean { diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 1a0a9f339..fa4637202 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -11,7 +11,8 @@ import type { MarkdownDocument, Node, } from './types.ts' -import MarkdownExit, { type Token } from 'markdown-exit' +import MarkdownExit, { type Token } from 'markdown-exit/core' +import type { LinkifyIt } from 'linkify-it' import components from './plugins/components.ts' import attributes from './plugins/attributes.ts' import taskList from './plugins/task-list.ts' @@ -41,6 +42,16 @@ let nextPluginId = 0 const pluginIds = new WeakMap() const sharedParsers = new Map() +// `markdown-exit/core` leaves linkify-it out, so bundles only fetch it once a +// parser with `linkify` runs. linkify-it 6 stopped matching `www.example.com` +// and `user:pass@` URLs by default; keep them linked as before. +let linkifyModule: Promise | undefined +async function createLinkify(): Promise { + linkifyModule ??= import('linkify-it').then((m) => m.LinkifyIt) + const Linkify = await linkifyModule + return new Linkify().set({ fuzzyLink: true, urlAuth: true }) +} + /** * Creates a parser function for Comark content. * @@ -195,6 +206,8 @@ export function createMarkdownParser plugin.pre!(state)) } + if (linkify && !parser.linkify) parser.linkify = await createLinkify() + try { state.tokens = withSpan(tracer, 'comark:tokenize', () => parser.parse(state.markdown, {})) } catch (e) { diff --git a/packages/comark/src/plugins/attributes.ts b/packages/comark/src/plugins/attributes.ts index d276d2492..c783837b6 100644 --- a/packages/comark/src/plugins/attributes.ts +++ b/packages/comark/src/plugins/attributes.ts @@ -9,8 +9,8 @@ * @see https://comark.dev/syntax/attributes */ -import type { PluginSimple, Renderer } from 'markdown-exit' -import { Token } from 'markdown-exit' +import type { PluginSimple, Renderer } from 'markdown-exit/core' +import { Token } from 'markdown-exit/core' import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from '../utils/helpers.ts' import { searchProps } from '../internal/parse/syntax/props.ts' diff --git a/packages/comark/src/plugins/binding.ts b/packages/comark/src/plugins/binding.ts index 819922746..9b07b551d 100644 --- a/packages/comark/src/plugins/binding.ts +++ b/packages/comark/src/plugins/binding.ts @@ -1,4 +1,4 @@ -import type { PluginWithOptions, MarkdownExit } from 'markdown-exit' +import type { PluginWithOptions, MarkdownExit } from 'markdown-exit/core' import { defineComarkPlugin } from 'comark' import type { MarkdownItPlugin, NodeHandler, Node } from 'comark' diff --git a/packages/comark/src/plugins/components.ts b/packages/comark/src/plugins/components.ts index d762e5e6a..9e2abcf9c 100644 --- a/packages/comark/src/plugins/components.ts +++ b/packages/comark/src/plugins/components.ts @@ -8,7 +8,7 @@ * @see https://comark.dev/syntax/components */ -import type { PluginSimple, Token } from 'markdown-exit' +import type { PluginSimple, Token } from 'markdown-exit/core' import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from '../utils/helpers.ts' import { findClosingBracket, parseBracketContent } from '../internal/parse/syntax/brackets.ts' diff --git a/packages/comark/src/plugins/html.ts b/packages/comark/src/plugins/html.ts index 28ec8835a..999f91696 100644 --- a/packages/comark/src/plugins/html.ts +++ b/packages/comark/src/plugins/html.ts @@ -35,7 +35,7 @@ * ``` */ -import { type StateBlock, Token, type MarkdownExit } from 'markdown-exit' +import { type StateBlock, Token, type MarkdownExit } from 'markdown-exit/core' import type { ComarkParseTokensState } from '../types.ts' import { defineComarkPlugin } from '../utils/helpers.ts' diff --git a/packages/comark/src/plugins/math.ts b/packages/comark/src/plugins/math.ts index c45337f51..40fccfe3f 100644 --- a/packages/comark/src/plugins/math.ts +++ b/packages/comark/src/plugins/math.ts @@ -1,4 +1,4 @@ -import type { MarkdownExit, StateInline, StateBlock } from 'markdown-exit' +import type { MarkdownExit, StateInline, StateBlock } from 'markdown-exit/core' import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from 'comark' import { findBracketClose, isBracketMath } from '../internal/bracket-math.ts' diff --git a/packages/comark/src/plugins/mermaid.ts b/packages/comark/src/plugins/mermaid.ts index 2f19e58be..c0b85973e 100644 --- a/packages/comark/src/plugins/mermaid.ts +++ b/packages/comark/src/plugins/mermaid.ts @@ -1,4 +1,4 @@ -import type { MarkdownExit } from 'markdown-exit' +import type { MarkdownExit } from 'markdown-exit/core' import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from 'comark' diff --git a/packages/comark/src/types.ts b/packages/comark/src/types.ts index 36c51e3ae..8149fdf39 100644 --- a/packages/comark/src/types.ts +++ b/packages/comark/src/types.ts @@ -1,6 +1,6 @@ import type { DumpOptions } from 'js-yaml' -import type MarkdownExit from 'markdown-exit' -import type { Token } from 'markdown-exit' +import type MarkdownExit from 'markdown-exit/core' +import type { Token } from 'markdown-exit/core' import type MarkdownIt from 'markdown-it' import type { AutoCloseOptions } from './internal/parse/auto-close/index.ts' diff --git a/packages/comark/test/linkify.test.ts b/packages/comark/test/linkify.test.ts new file mode 100644 index 000000000..82c74ad24 --- /dev/null +++ b/packages/comark/test/linkify.test.ts @@ -0,0 +1,45 @@ +import { execFileSync } from 'node:child_process' +import { describe, expect, it } from 'vitest' +import { parseMarkdown } from '../src/parse' + +describe('linkify', () => { + it('links bare domains and URLs with credentials', async () => { + const doc = await parseMarkdown('www.example.com and https://user:pw@example.com/a') + expect(doc.nodes).toEqual([ + [ + 'p', + {}, + ['a', { href: 'http://www.example.com' }, 'www.example.com'], + ' and ', + ['a', { href: 'https://user:pw@example.com/a' }, 'https://user:pw@example.com/a'], + ], + ]) + }) + + it('loads linkify-it only for parsers with linkify enabled', () => { + const output = execFileSync( + process.execPath, + [ + '--input-type=module', + '-e', + ` + import { registerHooks } from 'node:module' + const loaded = [] + registerHooks({ + load(url, context, next) { + if (url.includes('/linkify-it/')) loaded.push(url) + return next(url, context) + }, + }) + const { createMarkdownParser } = await import('comark') + await createMarkdownParser({ linkify: false })('https://comark.dev') + const before = loaded.length + await createMarkdownParser()('https://comark.dev') + console.log(before, loaded.length > 0) + `, + ], + { cwd: import.meta.dirname, encoding: 'utf8' } + ) + expect(output.trim()).toBe('0 true') + }) +}) diff --git a/packages/comark/test/parse/html-attribute-references.test.ts b/packages/comark/test/parse/html-attribute-references.test.ts new file mode 100644 index 000000000..0a77289df --- /dev/null +++ b/packages/comark/test/parse/html-attribute-references.test.ts @@ -0,0 +1,16 @@ +import { describe, expect, it } from 'vitest' +import { parseHtmlAttributes } from '../../src/internal/parse/utils' + +describe('character references in HTML attribute values', () => { + it.each([ + ['<b> &amp; ©', ' & Β©'], + ['ABC 😀', 'ABC πŸ˜€'], + ['� � � €', 'οΏ½ οΏ½ οΏ½ €'], + ['?a=1©=2& <', '?a=1©=2& <'], + ['©2 &foo; ¬it;', '©2 &foo; ¬it;'], + ['¬in& &backepsilonx', '¬in& &backepsilonx'], + ['&bogus; &# &#x; & &&', '&bogus; &# &#x; & &&'], + ])('%s', (value, expected) => { + expect(parseHtmlAttributes(`title="${value}"`).title).toBe(expected) + }) +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3cbfb09d6..0ce5d605f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -317,12 +317,18 @@ catalogs: beautiful-mermaid: specifier: ^1.1.3 version: 1.1.3 + character-entities: + specifier: ^2.0.2 + version: 2.0.2 + character-entities-legacy: + specifier: ^3.0.0 + version: 3.0.0 comark-linter: specifier: ^0.7.6 version: 0.7.6 entities: - specifier: ^7.0.0 - version: 7.0.1 + specifier: ^8.1.0 + version: 8.1.0 github-slugger: specifier: ^2.0.0 version: 2.0.0 @@ -335,9 +341,12 @@ catalogs: katex: specifier: ^0.19.1 version: 0.19.1 + linkify-it: + specifier: ^6.1.0 + version: 6.1.0 markdown-exit: - specifier: 1.3.0 - version: 1.3.0 + specifier: 2.1.0 + version: 2.1.0 markdown-it: specifier: ^15.0.3 version: 15.0.3 @@ -495,7 +504,7 @@ importers: version: link:packages/comark markdown-exit: specifier: 'catalog:' - version: 1.3.0 + version: 2.1.0 markdown-it: specifier: 'catalog:' version: 15.0.3 @@ -1425,18 +1434,24 @@ importers: beautiful-mermaid: specifier: 'catalog:' version: 1.1.3 - entities: + character-entities: specifier: 'catalog:' - version: 7.0.1 + version: 2.0.2 + character-entities-legacy: + specifier: 'catalog:' + version: 3.0.0 js-yaml: specifier: 'catalog:' version: 5.5.0 katex: specifier: 'catalog:' version: 0.19.1 + linkify-it: + specifier: 'catalog:' + version: 6.1.0 markdown-exit: specifier: 'catalog:' - version: 1.3.0 + version: 2.1.0 shiki: specifier: 'catalog:' version: 4.5.0 @@ -1450,6 +1465,9 @@ importers: '@types/markdown-it': specifier: 'catalog:' version: 14.2.0 + entities: + specifier: 'catalog:' + version: 8.1.0 github-slugger: specifier: 'catalog:' version: 2.0.0 @@ -8418,6 +8436,9 @@ packages: markdown-exit@1.3.0: resolution: {integrity: sha512-bsqlcm3Hk1ukcG1Al83pp3JjVobu4w1mpZz47OzLw8bCY8XchkCX+PXC32l2TH4nZ7p5WFg2NwpnLDXkY1X7Yw==} + markdown-exit@2.1.0: + resolution: {integrity: sha512-ffGj82OodjwgZ2tZtXBLXvJsMbvgtp2r+RDQgpAuWSk2Zi2zgNfQPyzVQFHAUV6Z/B/uQwqFHHEKNmeogIMsbw==} + markdown-it@15.0.3: resolution: {integrity: sha512-+Az7Ojz3iRGu8KYMvJ6xVhvrxP3eE+vEtJX75Ow88XBpcQNV/0lGX5ZynIIBftREo4DC2jsveAMDaeltmm8QvQ==} hasBin: true @@ -17921,6 +17942,14 @@ snapshots: punycode.js: 2.3.1 uc.micro: 2.1.0 + markdown-exit@2.1.0: + dependencies: + character-entities: 2.0.2 + linkify-it: 6.1.0 + mdurl: 2.1.0 + punycode.js: 2.3.1 + uc.micro: 3.0.0 + markdown-it@15.0.3: dependencies: argparse: 3.0.3 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index e6f19942c..0e32bcb79 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -90,13 +90,15 @@ catalog: comark: ^0.8.1 # Core comark dependencies - # Keep in the same major as markdown-exit's `entities` so installs dedupe to one copy. - entities: ^7.0.0 + character-entities: ^2.0.2 + character-entities-legacy: ^3.0.0 + entities: ^8.1.0 github-slugger: ^2.0.0 hast-util-to-string: ^3.0.1 js-yaml: ^5.5.0 katex: ^0.19.1 - markdown-exit: 1.3.0 + linkify-it: ^6.1.0 + markdown-exit: 2.1.0 "markdown-it": ^15.0.3 markdown-it-math: ^6.1.0 minimark: 0.2.0 @@ -186,6 +188,7 @@ minimumReleaseAgeExclude: - comark-content@0.2.0 || 0.4.1 - rangi@2.2.0 - nuxt-agent-discovery@0.7.0 + - markdown-exit@2.1.0 patchedDependencies: minimark: patches/minimark.patch From ea09bf3ff412ec629e8da61373f639a863f829c3 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 10:15:30 +0100 Subject: [PATCH 02/15] chore(core): describe shared parsers and linkify-it loading in present tense --- packages/comark/src/internal/entities.ts | 5 ++--- packages/comark/src/parse.ts | 10 ++++------ 2 files changed, 6 insertions(+), 9 deletions(-) diff --git a/packages/comark/src/internal/entities.ts b/packages/comark/src/internal/entities.ts index 1415c65e5..7bdbbe3e0 100644 --- a/packages/comark/src/internal/entities.ts +++ b/packages/comark/src/internal/entities.ts @@ -1,8 +1,7 @@ import { characterEntities } from 'character-entities' import { characterEntitiesLegacy } from 'character-entities-legacy' -// markdown-exit decodes with `character-entities`, so reusing it keeps a single -// entity table in bundles instead of shipping a second one from `entities`. +// Same table as markdown-exit, so bundles hold one copy. const own = Object.prototype.hasOwnProperty const legacy = new Set(characterEntitiesLegacy) @@ -81,7 +80,7 @@ export function decodeHTMLAttribute(input: string): string { const isValid = hex ? isHexDigit : isDigit let value = 0 while (end < length && isValid(input.charCodeAt(end))) { - // Clamp so overlong references stay out of range instead of overflowing. + // Clamped so overlong references stay out of range. value = Math.min(value * (hex ? 16 : 10) + Number.parseInt(input[end], 16), 0x110000) end++ } diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index fa4637202..0cfa2d84a 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -32,9 +32,8 @@ export { parseFrontmatter } from './internal/frontmatter.ts' // Re-export plugin utilities export { defineComarkPlugin } from './utils/helpers.ts' -// Constructing a `MarkdownExit` instance is expensive because `LinkifyIt` -// compiles its regexes in the constructor, and a configured instance holds no -// per-parse state, so parsers built from the same options share one. +// A configured `MarkdownExit` instance holds no per-parse state, so parsers +// built from the same options share one. // Bounded LRU: a caller that keeps minting fresh markdown-it plugin closures // (math/mermaid/binding factories) must not grow this without limit. const MAX_SHARED_PARSERS = 32 @@ -42,9 +41,8 @@ let nextPluginId = 0 const pluginIds = new WeakMap() const sharedParsers = new Map() -// `markdown-exit/core` leaves linkify-it out, so bundles only fetch it once a -// parser with `linkify` runs. linkify-it 6 stopped matching `www.example.com` -// and `user:pass@` URLs by default; keep them linked as before. +// Loaded on the first parse with `linkify`, so bundles without it skip linkify-it. +// `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. let linkifyModule: Promise | undefined async function createLinkify(): Promise { linkifyModule ??= import('linkify-it').then((m) => m.LinkifyIt) From fbc302594bbd437dcb54d9c2f19e2ee6ea6b5813 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 12:10:06 +0100 Subject: [PATCH 03/15] perf(core): create one linkifier when a new parser runs concurrent first parses --- packages/comark/src/parse.ts | 7 +++--- packages/comark/test/linkify.test.ts | 32 ++++++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 0cfa2d84a..83746fc29 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -44,10 +44,11 @@ const sharedParsers = new Map() // Loaded on the first parse with `linkify`, so bundles without it skip linkify-it. // `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. let linkifyModule: Promise | undefined -async function createLinkify(): Promise { +async function loadLinkify(parser: MarkdownExit): Promise { linkifyModule ??= import('linkify-it').then((m) => m.LinkifyIt) const Linkify = await linkifyModule - return new Linkify().set({ fuzzyLink: true, urlAuth: true }) + // Concurrent first parses all reach this point; the first one sets it. + parser.linkify ??= new Linkify().set({ fuzzyLink: true, urlAuth: true }) } /** @@ -204,7 +205,7 @@ export function createMarkdownParser plugin.pre!(state)) } - if (linkify && !parser.linkify) parser.linkify = await createLinkify() + if (linkify && !parser.linkify) await loadLinkify(parser) try { state.tokens = withSpan(tracer, 'comark:tokenize', () => parser.parse(state.markdown, {})) diff --git a/packages/comark/test/linkify.test.ts b/packages/comark/test/linkify.test.ts index 82c74ad24..2be2f6bb2 100644 --- a/packages/comark/test/linkify.test.ts +++ b/packages/comark/test/linkify.test.ts @@ -1,6 +1,19 @@ import { execFileSync } from 'node:child_process' -import { describe, expect, it } from 'vitest' -import { parseMarkdown } from '../src/parse' +import { describe, expect, it, vi } from 'vitest' +import type { MarkdownItPlugin } from 'comark' +import { createMarkdownParser, defineComarkPlugin, parseMarkdown } from '../src/parse' + +const linkifiers = vi.hoisted(() => ({ created: 0 })) +vi.mock('linkify-it', async (importOriginal) => { + const actual = await importOriginal() + class LinkifyIt extends actual.LinkifyIt { + constructor(...args: ConstructorParameters) { + super(...args) + linkifiers.created++ + } + } + return { ...actual, LinkifyIt } +}) describe('linkify', () => { it('links bare domains and URLs with credentials', async () => { @@ -16,6 +29,21 @@ describe('linkify', () => { ]) }) + it('creates one linkifier when a new parser runs several parses at once', async () => { + // A markdown-it plugin no other parser uses keeps this parser out of the shared cache. + const fresh = defineComarkPlugin(() => ({ + name: 'linkify-concurrent', + markdownItPlugins: [(() => {}) as unknown as MarkdownItPlugin], + })) + const parse = createMarkdownParser({ plugins: [fresh()] }) + const before = linkifiers.created + + const docs = await Promise.all(Array.from({ length: 10 }, () => parse('See https://comark.dev'))) + + expect(linkifiers.created - before).toBe(1) + expect(docs[9].nodes).toEqual([['p', {}, 'See ', ['a', { href: 'https://comark.dev' }, 'https://comark.dev']]]) + }) + it('loads linkify-it only for parsers with linkify enabled', () => { const output = execFileSync( process.execPath, From a2edc4a2ed5e208c27277e8d6f8169ec43a62371 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 12:52:24 +0100 Subject: [PATCH 04/15] test(react): load linkify-it before the streaming browser tests so the first parse settles inside act --- packages/comark-react/test/streaming.browser.test.tsx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/packages/comark-react/test/streaming.browser.test.tsx b/packages/comark-react/test/streaming.browser.test.tsx index 60bb1a580..1c950cf72 100644 --- a/packages/comark-react/test/streaming.browser.test.tsx +++ b/packages/comark-react/test/streaming.browser.test.tsx @@ -1,6 +1,7 @@ import React, { act, Component, StrictMode } from 'react' import { createRoot } from 'react-dom/client' -import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { afterEach, beforeAll, beforeEach, describe, expect, it } from 'vitest' +import { parseMarkdown } from 'comark' import type { ComarkPlugin, MarkdownDocument } from 'comark' import { MarkdownClient } from '../src/components/MarkdownClient' import { Markdown } from '../src/components/Markdown' @@ -9,6 +10,11 @@ import { defineMarkdownComponent } from '../src/index' Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true }) +// The first parse with linkify loads linkify-it, which settles outside `act`. +beforeAll(async () => { + await parseMarkdown('') +}) + let container: HTMLDivElement let root: ReturnType beforeEach(() => { From d31909ff180969132f53e430c8675b5655adc925 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 12:18:25 +0100 Subject: [PATCH 05/15] fix(core): install markdown-it plugins after linkify-it loads so they can configure md.linkify --- packages/comark/src/parse.ts | 34 +++++++++++++-------- packages/comark/test/linkify.test.ts | 22 +++++++++++++ packages/comark/test/parser-sharing.test.ts | 21 +++++++------ 3 files changed, 55 insertions(+), 22 deletions(-) diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 83746fc29..b1ff9a41f 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -39,16 +39,24 @@ export { defineComarkPlugin } from './utils/helpers.ts' const MAX_SHARED_PARSERS = 32 let nextPluginId = 0 const pluginIds = new WeakMap() -const sharedParsers = new Map() +const sharedParsers = new Map() + +interface SharedParser { + md: MarkdownExit + // With `linkify`, settles once linkify-it is loaded and the markdown-it plugins are installed. + ready?: Promise +} // Loaded on the first parse with `linkify`, so bundles without it skip linkify-it. -// `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. let linkifyModule: Promise | undefined -async function loadLinkify(parser: MarkdownExit): Promise { + +// markdown-it plugins may configure `md.linkify` when installed, so they run after it exists. +// `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. +async function installLinkify(md: MarkdownExit, mdPlugins: MarkdownExitPlugin[]): Promise { linkifyModule ??= import('linkify-it').then((m) => m.LinkifyIt) const Linkify = await linkifyModule - // Concurrent first parses all reach this point; the first one sets it. - parser.linkify ??= new Linkify().set({ fuzzyLink: true, urlAuth: true }) + md.linkify = new Linkify().set({ fuzzyLink: true, urlAuth: true }) + for (const fn of mdPlugins) md.use(fn) } /** @@ -127,20 +135,21 @@ export function createMarkdownParser pluginIds.get(fn) ?? (pluginIds.set(fn, nextPluginId), nextPluginId++)), ].join(',') - let parser = sharedParsers.get(key) - if (parser) { + let shared = sharedParsers.get(key) + if (shared) { // Touch for LRU: Map iteration order is insertion order. sharedParsers.delete(key) - sharedParsers.set(key, parser) + sharedParsers.set(key, shared) } else { - parser = new MarkdownExit({ linkify }).enable(['table', 'strikethrough']) - for (const fn of mdPlugins) parser.use(fn) + shared = { md: new MarkdownExit({ linkify }).enable(['table', 'strikethrough']) } + if (!linkify) for (const fn of mdPlugins) shared.md.use(fn) if (sharedParsers.size >= MAX_SHARED_PARSERS) { const oldestKey = sharedParsers.keys().next().value if (oldestKey !== undefined) sharedParsers.delete(oldestKey) } - sharedParsers.set(key, parser) + sharedParsers.set(key, shared) } + const parser = shared.md let lastOutput: MarkdownDocument | null = null let lastInput: string | null = null @@ -205,7 +214,8 @@ export function createMarkdownParser plugin.pre!(state)) } - if (linkify && !parser.linkify) await loadLinkify(parser) + // Same key, same plugin functions, so any parser sharing this instance can install them. + if (linkify) await (shared.ready ??= installLinkify(parser, mdPlugins)) try { state.tokens = withSpan(tracer, 'comark:tokenize', () => parser.parse(state.markdown, {})) diff --git a/packages/comark/test/linkify.test.ts b/packages/comark/test/linkify.test.ts index 2be2f6bb2..5c14de40c 100644 --- a/packages/comark/test/linkify.test.ts +++ b/packages/comark/test/linkify.test.ts @@ -1,6 +1,7 @@ import { execFileSync } from 'node:child_process' import { describe, expect, it, vi } from 'vitest' import type { MarkdownItPlugin } from 'comark' +import type { MarkdownExit } from 'markdown-exit/core' import { createMarkdownParser, defineComarkPlugin, parseMarkdown } from '../src/parse' const linkifiers = vi.hoisted(() => ({ created: 0 })) @@ -29,6 +30,27 @@ describe('linkify', () => { ]) }) + it('gives markdown-it plugins md.linkify when they are installed', async () => { + // Mention plugins register a linkify schema when installed. + const mention = defineComarkPlugin(() => ({ + name: 'linkify-mention', + markdownItPlugins: [ + ((md: MarkdownExit) => { + md.linkify.add('@', { + validate: (text: string, pos: number) => /^[\w-]+/.exec(text.slice(pos))?.[0].length ?? 0, + normalize: (match) => { + match.url = `https://github.com/${match.url.slice(1)}` + }, + }) + }) as unknown as MarkdownItPlugin, + ], + })) + + const doc = await createMarkdownParser({ plugins: [mention()] })('hi @comark') + + expect(doc.nodes).toEqual([['p', {}, 'hi ', ['a', { href: 'https://github.com/comark' }, '@comark']]]) + }) + it('creates one linkifier when a new parser runs several parses at once', async () => { // A markdown-it plugin no other parser uses keeps this parser out of the shared cache. const fresh = defineComarkPlugin(() => ({ diff --git a/packages/comark/test/parser-sharing.test.ts b/packages/comark/test/parser-sharing.test.ts index fe38a3048..8f9bc4e20 100644 --- a/packages/comark/test/parser-sharing.test.ts +++ b/packages/comark/test/parser-sharing.test.ts @@ -5,7 +5,8 @@ import binding from '../src/plugins/binding' // The shared instance is internal, so it is observed through the public API: a // markdown-it plugin function runs once per instance, so counting how often it -// is registered counts the instances that were built. +// is registered counts the instances that were built. With linkify on, plugins +// install on the first parse, so these parsers turn it off to install at build. let stableUses = 0 const stableMdPlugin = (() => { stableUses++ @@ -32,7 +33,7 @@ describe('parser sharing', () => { const before = stableUses for (let i = 0; i < 20; i++) { - createMarkdownParser({ plugins: [plugin] }) + createMarkdownParser({ linkify: false, plugins: [plugin] }) } expect(stableUses - before).toBe(1) @@ -42,7 +43,7 @@ describe('parser sharing', () => { const before = closureUses for (let i = 0; i < 5; i++) { - createMarkdownParser({ plugins: [closurePlugin()] }) + createMarkdownParser({ linkify: false, plugins: [closurePlugin()] }) } expect(closureUses - before).toBe(5) @@ -68,24 +69,24 @@ describe('parser sharing', () => { markdownItPlugins: [oldestMdPlugin], }))() - createMarkdownParser({ plugins: [markedPlugin] }) - createMarkdownParser({ plugins: [oldestPlugin] }) + createMarkdownParser({ linkify: false, plugins: [markedPlugin] }) + createMarkdownParser({ linkify: false, plugins: [oldestPlugin] }) // Capacity is 32. Keep both named entries in the cache, then refresh // markedPlugin before inserting one more key so only oldestPlugin ages out. for (let i = 0; i < 30; i++) { - createMarkdownParser({ plugins: [closurePlugin()] }) + createMarkdownParser({ linkify: false, plugins: [closurePlugin()] }) } expect(markedUses).toBe(1) expect(oldestUses).toBe(1) - createMarkdownParser({ plugins: [markedPlugin] }) - createMarkdownParser({ plugins: [closurePlugin()] }) + createMarkdownParser({ linkify: false, plugins: [markedPlugin] }) + createMarkdownParser({ linkify: false, plugins: [closurePlugin()] }) - createMarkdownParser({ plugins: [oldestPlugin] }) + createMarkdownParser({ linkify: false, plugins: [oldestPlugin] }) expect(oldestUses).toBe(2) - createMarkdownParser({ plugins: [markedPlugin] }) + createMarkdownParser({ linkify: false, plugins: [markedPlugin] }) expect(markedUses).toBe(1) }) From 64d145123468e7ae27be4c8480b3eef273e73319 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 12:58:03 +0100 Subject: [PATCH 06/15] fix(core): keep linkify options when the markdown-exit root entry is loaded --- packages/comark/src/parse.ts | 3 ++- .../comark/test/linkify-root-entry.test.ts | 22 +++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 packages/comark/test/linkify-root-entry.test.ts diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index b1ff9a41f..9fd9170bf 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -51,7 +51,8 @@ interface SharedParser { let linkifyModule: Promise | undefined // markdown-it plugins may configure `md.linkify` when installed, so they run after it exists. -// `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. +// `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. This replaces the plain +// instance that the root `markdown-exit` entry gives every parser once something imports it. async function installLinkify(md: MarkdownExit, mdPlugins: MarkdownExitPlugin[]): Promise { linkifyModule ??= import('linkify-it').then((m) => m.LinkifyIt) const Linkify = await linkifyModule diff --git a/packages/comark/test/linkify-root-entry.test.ts b/packages/comark/test/linkify-root-entry.test.ts new file mode 100644 index 000000000..0504d94d1 --- /dev/null +++ b/packages/comark/test/linkify-root-entry.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from 'vitest' +import { createMarkdownParser } from '../src/parse' + +// The root `markdown-exit` entry registers a plain LinkifyIt factory for every +// instance, so it runs in its own file to keep that global out of other tests. +describe('linkify with the markdown-exit root entry loaded', () => { + it('still links bare domains and URLs with credentials', async () => { + await import('markdown-exit') + + const doc = await createMarkdownParser()('www.example.com and https://user:pw@example.com/a') + + expect(doc.nodes).toEqual([ + [ + 'p', + {}, + ['a', { href: 'http://www.example.com' }, 'www.example.com'], + ' and ', + ['a', { href: 'https://user:pw@example.com/a' }, 'https://user:pw@example.com/a'], + ], + ]) + }) +}) From 6e2c1eac5d424d9e66573165362073e9f08ca0aa Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 13:10:00 +0100 Subject: [PATCH 07/15] perf(core): load linkify-it 5, whose default fuzzy links cost less than linkify-it 6's --- packages/comark/package.json | 1 + packages/comark/src/parse.ts | 12 +++++++----- packages/comark/test/linkify.test.ts | 8 ++++---- pnpm-lock.yaml | 12 +++++++++--- pnpm-workspace.yaml | 3 ++- 5 files changed, 23 insertions(+), 13 deletions(-) diff --git a/packages/comark/package.json b/packages/comark/package.json index 8864a64e9..de6237dc8 100644 --- a/packages/comark/package.json +++ b/packages/comark/package.json @@ -78,6 +78,7 @@ "devDependencies": { "@json-render/core": "catalog:", "@shikijs/twoslash": "catalog:", + "@types/linkify-it": "catalog:", "@types/markdown-it": "catalog:", "entities": "catalog:", "github-slugger": "catalog:", diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 9fd9170bf..2538693c4 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -12,7 +12,7 @@ import type { Node, } from './types.ts' import MarkdownExit, { type Token } from 'markdown-exit/core' -import type { LinkifyIt } from 'linkify-it' +import type LinkifyIt from 'linkify-it' import components from './plugins/components.ts' import attributes from './plugins/attributes.ts' import taskList from './plugins/task-list.ts' @@ -51,12 +51,14 @@ interface SharedParser { let linkifyModule: Promise | undefined // markdown-it plugins may configure `md.linkify` when installed, so they run after it exists. -// `fuzzyLink` and `urlAuth` link `www.example.com` and `user:pass@` URLs. This replaces the plain -// instance that the root `markdown-exit` entry gives every parser once something imports it. +// This also replaces the instance that the root `markdown-exit` entry gives every parser once +// something imports it. linkify-it 5 links `www.example.com` and `user:pass@` URLs by default; +// linkify-it 6 needs `fuzzyLink` for that, which made streaming chat text about 1.8x slower. async function installLinkify(md: MarkdownExit, mdPlugins: MarkdownExitPlugin[]): Promise { - linkifyModule ??= import('linkify-it').then((m) => m.LinkifyIt) + linkifyModule ??= import('linkify-it').then((m) => m.default) const Linkify = await linkifyModule - md.linkify = new Linkify().set({ fuzzyLink: true, urlAuth: true }) + // markdown-exit types this as linkify-it 6. It only calls `test`, `match` and `matchAtStart`, which 5 has too. + md.linkify = new Linkify() as unknown as MarkdownExit['linkify'] for (const fn of mdPlugins) md.use(fn) } diff --git a/packages/comark/test/linkify.test.ts b/packages/comark/test/linkify.test.ts index 5c14de40c..6536a9f72 100644 --- a/packages/comark/test/linkify.test.ts +++ b/packages/comark/test/linkify.test.ts @@ -6,14 +6,14 @@ import { createMarkdownParser, defineComarkPlugin, parseMarkdown } from '../src/ const linkifiers = vi.hoisted(() => ({ created: 0 })) vi.mock('linkify-it', async (importOriginal) => { - const actual = await importOriginal() - class LinkifyIt extends actual.LinkifyIt { - constructor(...args: ConstructorParameters) { + const { default: LinkifyIt } = await importOriginal() + class CountingLinkifyIt extends LinkifyIt { + constructor(...args: ConstructorParameters) { super(...args) linkifiers.created++ } } - return { ...actual, LinkifyIt } + return { default: CountingLinkifyIt } }) describe('linkify', () => { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 0ce5d605f..00228d601 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -257,6 +257,9 @@ catalogs: '@types/json-schema': specifier: ^7.0.15 version: 7.0.15 + '@types/linkify-it': + specifier: ^5.0.0 + version: 5.0.0 '@types/markdown-it': specifier: ^14.2.0 version: 14.2.0 @@ -342,8 +345,8 @@ catalogs: specifier: ^0.19.1 version: 0.19.1 linkify-it: - specifier: ^6.1.0 - version: 6.1.0 + specifier: ^5.0.0 + version: 5.0.2 markdown-exit: specifier: 2.1.0 version: 2.1.0 @@ -1448,7 +1451,7 @@ importers: version: 0.19.1 linkify-it: specifier: 'catalog:' - version: 6.1.0 + version: 5.0.2 markdown-exit: specifier: 'catalog:' version: 2.1.0 @@ -1462,6 +1465,9 @@ importers: '@shikijs/twoslash': specifier: 'catalog:' version: 4.5.0(supports-color@10.2.2)(typescript@6.0.3) + '@types/linkify-it': + specifier: 'catalog:' + version: 5.0.0 '@types/markdown-it': specifier: 'catalog:' version: 14.2.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 0e32bcb79..01457bde0 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -57,6 +57,7 @@ catalog: # Types "@types/json-schema": ^7.0.15 + "@types/linkify-it": ^5.0.0 "@types/markdown-it": ^14.2.0 "@types/node": ^26.6.6 "@types/react": ^19.3.0 @@ -97,7 +98,7 @@ catalog: hast-util-to-string: ^3.0.1 js-yaml: ^5.5.0 katex: ^0.19.1 - linkify-it: ^6.1.0 + linkify-it: ^5.0.0 markdown-exit: 2.1.0 "markdown-it": ^15.0.3 markdown-it-math: ^6.1.0 From 45a36e3a26b2b489275958534f9a4bfd86721ecc Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 13:18:44 +0100 Subject: [PATCH 08/15] fix(core): retry loading linkify-it on the next parse after a failed import --- packages/comark/src/parse.ts | 19 +++++++++++++------ packages/comark/test/linkify-retry.test.ts | 22 ++++++++++++++++++++++ 2 files changed, 35 insertions(+), 6 deletions(-) create mode 100644 packages/comark/test/linkify-retry.test.ts diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index 2538693c4..c35db4796 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -54,12 +54,19 @@ let linkifyModule: Promise | undefined // This also replaces the instance that the root `markdown-exit` entry gives every parser once // something imports it. linkify-it 5 links `www.example.com` and `user:pass@` URLs by default; // linkify-it 6 needs `fuzzyLink` for that, which made streaming chat text about 1.8x slower. -async function installLinkify(md: MarkdownExit, mdPlugins: MarkdownExitPlugin[]): Promise { - linkifyModule ??= import('linkify-it').then((m) => m.default) - const Linkify = await linkifyModule +async function installLinkify(shared: SharedParser, mdPlugins: MarkdownExitPlugin[]): Promise { + let Linkify: typeof LinkifyIt + try { + Linkify = await (linkifyModule ??= import('linkify-it').then((m) => m.default)) + } catch (error) { + // Retry a failed load, such as a chunk fetch, on the next parse. + linkifyModule = undefined + shared.ready = undefined + throw error + } // markdown-exit types this as linkify-it 6. It only calls `test`, `match` and `matchAtStart`, which 5 has too. - md.linkify = new Linkify() as unknown as MarkdownExit['linkify'] - for (const fn of mdPlugins) md.use(fn) + shared.md.linkify = new Linkify() as unknown as MarkdownExit['linkify'] + for (const fn of mdPlugins) shared.md.use(fn) } /** @@ -218,7 +225,7 @@ export function createMarkdownParser parser.parse(state.markdown, {})) diff --git a/packages/comark/test/linkify-retry.test.ts b/packages/comark/test/linkify-retry.test.ts new file mode 100644 index 000000000..7b3428364 --- /dev/null +++ b/packages/comark/test/linkify-retry.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it, vi } from 'vitest' +import { createMarkdownParser } from '../src/parse' + +const load = vi.hoisted(() => ({ fail: true })) +vi.mock('linkify-it', async (importOriginal) => { + if (load.fail) { + load.fail = false + throw new Error('Failed to fetch dynamically imported module') + } + return importOriginal() +}) + +describe('linkify-it load failure', () => { + it('retries the import on the next parse', async () => { + const parse = createMarkdownParser() + + await expect(parse('https://comark.dev')).rejects.toThrow() + const doc = await parse('https://comark.dev') + + expect(doc.nodes).toEqual([['p', {}, ['a', { href: 'https://comark.dev' }, 'https://comark.dev']]]) + }) +}) From 099c97e736da07902ab58232304fa037ea70c0f2 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 13:29:01 +0100 Subject: [PATCH 09/15] fix(core): set up a fresh parser on the next parse after a markdown-it plugin throws --- packages/comark/src/parse.ts | 22 +++++++++------- packages/comark/test/linkify-retry.test.ts | 29 ++++++++++++++++++++-- 2 files changed, 40 insertions(+), 11 deletions(-) diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index c35db4796..d4533594a 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -55,18 +55,23 @@ let linkifyModule: Promise | undefined // something imports it. linkify-it 5 links `www.example.com` and `user:pass@` URLs by default; // linkify-it 6 needs `fuzzyLink` for that, which made streaming chat text about 1.8x slower. async function installLinkify(shared: SharedParser, mdPlugins: MarkdownExitPlugin[]): Promise { - let Linkify: typeof LinkifyIt try { - Linkify = await (linkifyModule ??= import('linkify-it').then((m) => m.default)) + const Linkify = await (linkifyModule ??= import('linkify-it').then((m) => m.default)) + // markdown-exit types this as linkify-it 6. It only calls `test`, `match` and `matchAtStart`, which 5 has too. + shared.md.linkify = new Linkify() as unknown as MarkdownExit['linkify'] + for (const fn of mdPlugins) shared.md.use(fn) } catch (error) { - // Retry a failed load, such as a chunk fetch, on the next parse. + // Start over on the next parse: retry a failed load, such as a chunk fetch, and drop + // an instance that a throwing plugin left half set up. linkifyModule = undefined + shared.md = createMarkdownExit(true) shared.ready = undefined throw error } - // markdown-exit types this as linkify-it 6. It only calls `test`, `match` and `matchAtStart`, which 5 has too. - shared.md.linkify = new Linkify() as unknown as MarkdownExit['linkify'] - for (const fn of mdPlugins) shared.md.use(fn) +} + +function createMarkdownExit(linkify: boolean): MarkdownExit { + return new MarkdownExit({ linkify }).enable(['table', 'strikethrough']) } /** @@ -151,7 +156,7 @@ export function createMarkdownParser= MAX_SHARED_PARSERS) { const oldestKey = sharedParsers.keys().next().value @@ -159,7 +164,6 @@ export function createMarkdownParser parser.parse(state.markdown, {})) + state.tokens = withSpan(tracer, 'comark:tokenize', () => shared.md.parse(state.markdown, {})) } catch (e) { // in case of streaming, return the previous output if parsing fails // This is to avoid resetting the tree to an empty state on failure diff --git a/packages/comark/test/linkify-retry.test.ts b/packages/comark/test/linkify-retry.test.ts index 7b3428364..b3408c021 100644 --- a/packages/comark/test/linkify-retry.test.ts +++ b/packages/comark/test/linkify-retry.test.ts @@ -1,5 +1,7 @@ import { describe, expect, it, vi } from 'vitest' -import { createMarkdownParser } from '../src/parse' +import type { MarkdownItPlugin } from 'comark' +import type { MarkdownExit } from 'markdown-exit/core' +import { createMarkdownParser, defineComarkPlugin } from '../src/parse' const load = vi.hoisted(() => ({ fail: true })) vi.mock('linkify-it', async (importOriginal) => { @@ -10,7 +12,7 @@ vi.mock('linkify-it', async (importOriginal) => { return importOriginal() }) -describe('linkify-it load failure', () => { +describe('linkify setup failure', () => { it('retries the import on the next parse', async () => { const parse = createMarkdownParser() @@ -19,4 +21,27 @@ describe('linkify-it load failure', () => { expect(doc.nodes).toEqual([['p', {}, ['a', { href: 'https://comark.dev' }, 'https://comark.dev']]]) }) + + it('installs plugins on a fresh instance after a plugin throws', async () => { + let installs = 0 + let runs = 0 + const flaky = defineComarkPlugin(() => ({ + name: 'flaky', + markdownItPlugins: [ + ((md: MarkdownExit) => { + md.core.ruler.push('count-runs', () => { + runs++ + }) + if (installs++ === 0) throw new Error('plugin failed') + }) as unknown as MarkdownItPlugin, + ], + })) + const parse = createMarkdownParser({ plugins: [flaky()] }) + + await expect(parse('text')).rejects.toThrow('plugin failed') + await parse('text') + + // The rule from the failed install is gone, so it runs once. + expect(runs).toBe(1) + }) }) From 21f27ad071b87f5f98eeb2cbc911aa8ede388778 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 14:15:34 +0100 Subject: [PATCH 10/15] fix(core): give markdown-it plugins md.linkify when linkify is off markdown-exit/core has no linkify-it, so a plugin that calls md.linkify.add() threw while a parser with linkify: false was created. Such parsers now load linkify-it on the first parse, only when a plugin fails to install without it. --- packages/comark/src/parse.ts | 23 +++++++++++++++++------ packages/comark/test/linkify.test.ts | 5 ++++- 2 files changed, 21 insertions(+), 7 deletions(-) diff --git a/packages/comark/src/parse.ts b/packages/comark/src/parse.ts index d4533594a..d17905092 100644 --- a/packages/comark/src/parse.ts +++ b/packages/comark/src/parse.ts @@ -45,16 +45,19 @@ interface SharedParser { md: MarkdownExit // With `linkify`, settles once linkify-it is loaded and the markdown-it plugins are installed. ready?: Promise + // Without `linkify`, set when a markdown-it plugin needs `md.linkify` to install. + needsLinkify?: boolean } -// Loaded on the first parse with `linkify`, so bundles without it skip linkify-it. +// Loaded on the first parse that needs it, so bundles without it skip linkify-it. let linkifyModule: Promise | undefined // markdown-it plugins may configure `md.linkify` when installed, so they run after it exists. // This also replaces the instance that the root `markdown-exit` entry gives every parser once // something imports it. linkify-it 5 links `www.example.com` and `user:pass@` URLs by default; -// linkify-it 6 needs `fuzzyLink` for that, which made streaming chat text about 1.8x slower. -async function installLinkify(shared: SharedParser, mdPlugins: MarkdownExitPlugin[]): Promise { +// linkify-it 6 needs `fuzzyLink` for that, which made streaming chat text about 1.8x slower +// (markdown-it/linkify-it#126). +async function installLinkify(shared: SharedParser, mdPlugins: MarkdownExitPlugin[], linkify: boolean): Promise { try { const Linkify = await (linkifyModule ??= import('linkify-it').then((m) => m.default)) // markdown-exit types this as linkify-it 6. It only calls `test`, `match` and `matchAtStart`, which 5 has too. @@ -64,7 +67,7 @@ async function installLinkify(shared: SharedParser, mdPlugins: MarkdownExitPlugi // Start over on the next parse: retry a failed load, such as a chunk fetch, and drop // an instance that a throwing plugin left half set up. linkifyModule = undefined - shared.md = createMarkdownExit(true) + shared.md = createMarkdownExit(linkify) shared.ready = undefined throw error } @@ -157,7 +160,15 @@ export function createMarkdownParser= MAX_SHARED_PARSERS) { const oldestKey = sharedParsers.keys().next().value if (oldestKey !== undefined) sharedParsers.delete(oldestKey) @@ -229,7 +240,7 @@ export function createMarkdownParser shared.md.parse(state.markdown, {})) diff --git a/packages/comark/test/linkify.test.ts b/packages/comark/test/linkify.test.ts index 6536a9f72..db2acff0e 100644 --- a/packages/comark/test/linkify.test.ts +++ b/packages/comark/test/linkify.test.ts @@ -30,7 +30,7 @@ describe('linkify', () => { ]) }) - it('gives markdown-it plugins md.linkify when they are installed', async () => { + it('gives markdown-it plugins md.linkify when they are installed, also with linkify off', async () => { // Mention plugins register a linkify schema when installed. const mention = defineComarkPlugin(() => ({ name: 'linkify-mention', @@ -49,6 +49,9 @@ describe('linkify', () => { const doc = await createMarkdownParser({ plugins: [mention()] })('hi @comark') expect(doc.nodes).toEqual([['p', {}, 'hi ', ['a', { href: 'https://github.com/comark' }, '@comark']]]) + + const plain = await createMarkdownParser({ linkify: false, plugins: [mention()] })('hi @comark') + expect(plain.nodes).toEqual([['p', {}, 'hi @comark']]) }) it('creates one linkifier when a new parser runs several parses at once', async () => { From 7195d969a8bfbe247b39418982a5205346858fa5 Mon Sep 17 00:00:00 2001 From: onmax Date: Tue, 3 Nov 2026 20:07:00 +0100 Subject: [PATCH 11/15] test(core): update published bundle size --- test/bundle.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/bundle.test.ts b/test/bundle.test.ts index fee333412..5f1aa41d8 100644 --- a/test/bundle.test.ts +++ b/test/bundle.test.ts @@ -67,7 +67,7 @@ describe('package bundle size', { timeout: 60_000 }, () => { "@comark/react": "39.6k (76 files)", "@comark/svelte": "46.8k (84 files)", "@comark/vue": "56.4k (80 files)", - "comark": "402k (158 files)", + "comark": "407k (160 files)", } `) }) From c68a2846d3f133894052873e8ff50b24fff7c9c1 Mon Sep 17 00:00:00 2001 From: Farnabaz Date: Thu, 5 Nov 2026 15:00:55 +0100 Subject: [PATCH 12/15] feat(linkify)!: extract linkify into a default plugin on linkify-it 6 Linkify is now comark/plugins/linkify, registered by default via registerDefaultPlugins. linkify() accepts linkify-it options (fuzzyLink, fuzzyEmail, fuzzyIP, urlAuth, tlds, maxLength). The core parser no longer has any linkify logic; with comark/core, add linkify() to plugins. The linkify parser option is deprecated. It still works, takes precedence over registerDefaultPlugins, and logs a warning once. BREAKING CHANGE: linkify-it 6 does not link domains without a scheme (www.example.com) or URLs with credentials (https://user:pass@example.com) by default. Use linkify({ fuzzyLink: true, urlAuth: true }) to restore the previous behavior. --- AGENTS.md | 5 +- docs/app/components/Playground.vue | 26 ++- docs/content/2.syntax/1.markdown.md | 2 +- docs/content/3.rendering/2.html.md | 4 +- docs/content/3.rendering/3.vue.md | 4 +- docs/content/3.rendering/5.react.md | 4 +- docs/content/3.rendering/8.ansi.md | 4 +- docs/content/4.plugins/0.defaults/linkify.md | 68 ++++++++ docs/content/4.plugins/index.md | 6 +- docs/content/5.reference/1.parse.md | 6 +- docs/content/5.reference/3.reference.md | 2 +- .../test/define-component.test.ts | 2 +- .../test/incremental-streaming.svelte.test.ts | 4 +- packages/comark/package.json | 1 - packages/comark/src/core.ts | 71 ++------- packages/comark/src/index.ts | 26 ++- packages/comark/src/plugins/linkify.ts | 44 ++++++ packages/comark/src/types.ts | 16 +- packages/comark/test/linkify-retry.test.ts | 30 +--- .../comark/test/linkify-root-entry.test.ts | 14 +- packages/comark/test/linkify.test.ts | 148 +++++++++++------- packages/comark/test/parser-sharing.test.ts | 40 +++-- pnpm-lock.yaml | 12 +- pnpm-workspace.yaml | 3 +- 24 files changed, 334 insertions(+), 208 deletions(-) create mode 100644 docs/content/4.plugins/0.defaults/linkify.md create mode 100644 packages/comark/src/plugins/linkify.ts diff --git a/AGENTS.md b/AGENTS.md index 1ca27de9c..ad706e934 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,6 +76,7 @@ packages/comark/ β”‚ β”‚ β”œβ”€β”€ heading-links.ts # Links headings to their own `id` β”‚ β”‚ β”œβ”€β”€ headings.ts # Deprecated alias β†’ title-description (remove next major) β”‚ β”‚ β”œβ”€β”€ json-render.ts # `json-render` spec fences expanded into nodes +β”‚ β”‚ β”œβ”€β”€ linkify.ts # Bare URL autolinks via linkify-it 6 (default via registerDefaultPlugins; linkify-it options, fuzzyLink opt-in) β”‚ β”‚ β”œβ”€β”€ punctuation.ts # Smart quotes and dashes β”‚ β”‚ β”œβ”€β”€ shiki.ts # Shiki with bundled default theme + language loaders (peer: shiki) β”‚ β”‚ β”œβ”€β”€ shiki/core.ts # Shiki without default theme/language imports @@ -532,6 +533,7 @@ import titleDescription from 'comark/plugins/title-description' import headingLinks from 'comark/plugins/heading-links' import punctuation from 'comark/plugins/punctuation' import jsonRender from 'comark/plugins/json-render' +import linkify from 'comark/plugins/linkify' // default via registerDefaultPlugins; add explicitly with comark/core import security from 'comark/plugins/security' import summary from 'comark/plugins/summary' import taskList from 'comark/plugins/task-list' // default via registerDefaultPlugins @@ -653,7 +655,8 @@ const result = await parseMarkdown(markdownContent, { autoUnwrap: true, // Remove

wrappers from single-paragraph containers autoClose: true, // Auto-close incomplete syntax; also accepts (markdown) => string unwrap: 'p', // Strip top-level wrapper tags (MDC unwrap); merges paragraphs - registerDefaultPlugins: true, // frontmatter, html, alert, task-list, components, attributes; false to disable + registerDefaultPlugins: true, // linkify, frontmatter, html, alert, task-list, components, attributes; false to disable + // linkify: false // deprecated (warns): use registerDefaultPlugins: false + linkify() }) result.nodes // Node[] diff --git a/docs/app/components/Playground.vue b/docs/app/components/Playground.vue index a7e963a40..6ea9087c5 100644 --- a/docs/app/components/Playground.vue +++ b/docs/app/components/Playground.vue @@ -14,6 +14,13 @@ import titleDescription from '@comark/nuxt/plugins/title-description' import toc from '@comark/nuxt/plugins/toc' import summary from '@comark/nuxt/plugins/summary' import security from '@comark/nuxt/plugins/security' +import linkify from '@comark/nuxt/plugins/linkify' +import frontmatter from '@comark/nuxt/plugins/frontmatter' +import html from '@comark/nuxt/plugins/html' +import alert from '@comark/nuxt/plugins/alert' +import taskList from '@comark/nuxt/plugins/task-list' +import components from '@comark/nuxt/plugins/components' +import attributes from '@comark/nuxt/plugins/attributes' import { renderMarkdown } from 'comark/render' import { Splitpanes, Pane } from 'splitpanes' @@ -209,11 +216,19 @@ const parseOptionDefs = [ }, ] as const -const activePlugins = computed(() => - pluginDefs +// The other defaults always run; registering them explicitly lets linkify be toggled on its own. +const activePlugins = computed(() => [ + ...(parseOptions.value.linkify ? [linkify()] : []), + frontmatter(), + html(), + alert(), + taskList(), + components(), + attributes(), + ...pluginDefs .filter((p) => pluginToggles.value[p.key as keyof typeof pluginToggles.value]) - .map((p) => p.factory() as ComarkPlugin) -) + .map((p) => p.factory() as ComarkPlugin), +]) const enabledPluginCount = computed(() => Object.values(pluginToggles.value).filter(Boolean).length) @@ -258,7 +273,7 @@ async function updatePreview(): Promise { plugins: activePlugins.value, autoUnwrap: parseOptions.value.autoUnwrap, autoClose: parseOptions.value.autoClose, - linkify: parseOptions.value.linkify ?? true, + registerDefaultPlugins: false, }) document.value = result parseTime.value = Math.round((performance.now() - start) * 10) / 10 @@ -397,6 +412,7 @@ watch(completion, async (md) => { plugins: activePlugins.value, autoUnwrap: parseOptions.value.autoUnwrap, autoClose: true, + registerDefaultPlugins: false, }) document.value = result } catch { diff --git a/docs/content/2.syntax/1.markdown.md b/docs/content/2.syntax/1.markdown.md index 6bc30dc13..237425428 100644 --- a/docs/content/2.syntax/1.markdown.md +++ b/docs/content/2.syntax/1.markdown.md @@ -130,7 +130,7 @@ Text nodes in Comark are plain strings, similar to HTML text nodes. To add custo Add custom attributes to links and images with the [Attributes](/syntax/attributes) syntax: `[Link](url){target="_blank"}`. :: -Bare URLs like `https://example.com` are automatically converted into clickable links. Disable this with the [`linkify`](/reference/parse#options) option (`{ linkify: false }`). +Bare URLs like `https://example.com` are automatically converted into clickable links. Domains without a scheme, like `www.example.com`, need the plugin's `fuzzyLink` option. This comes from the default [linkify plugin](/plugins/defaults/linkify), which is left out with `registerDefaultPlugins: false`. ## Blockquotes diff --git a/docs/content/3.rendering/2.html.md b/docs/content/3.rendering/2.html.md index 597d25372..c24e91266 100644 --- a/docs/content/3.rendering/2.html.md +++ b/docs/content/3.rendering/2.html.md @@ -95,8 +95,8 @@ This is a **bold** statement with a [link](https://example.com). | [`transformNode`](#transformnode) | `NodeTransform \| NodeTransform[]` | `undefined` | Change the tag or props of element nodes right before they render | | `autoClose` | `boolean` | `true` | Close incomplete Markdown and components before parsing | | `autoUnwrap` | `boolean` | `true` | Remove a single paragraph wrapper inside components | -| `linkify` | `boolean` | `true` | Convert URL-like text into links | -| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | +| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead | +| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | | `unwrap` | `boolean \| string \| string[]` | `false` | Remove selected wrapper tags from the parsed document | `renderHtml()` accepts all [`ParserOptions`](/reference/parse#options) in addition to the renderer options above. diff --git a/docs/content/3.rendering/3.vue.md b/docs/content/3.rendering/3.vue.md index 8bc368f91..6a91b3717 100644 --- a/docs/content/3.rendering/3.vue.md +++ b/docs/content/3.rendering/3.vue.md @@ -379,8 +379,8 @@ import { AppMarkdown } from './markdown' | `name` | `string` | `undefined` | Component name for debugging | | `autoUnwrap` | `boolean` | `true` | Automatically unwrap single block elements | | `autoClose` | `boolean` | `true` | Auto-close incomplete markdown syntax | -| `linkify` | `boolean` | `true` | Auto-convert URL-like text into links | -| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | +| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead | +| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | | [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins | | [`components`](#components) | `Record` | `{}` | Custom Vue component mappings | | [`transformNode`](#transformnode) | `NodeTransform \| NodeTransform[]` | `undefined` | Node transforms that run before the instance's own `transformNode` | diff --git a/docs/content/3.rendering/5.react.md b/docs/content/3.rendering/5.react.md index 7c5c04088..6b6aeeaac 100644 --- a/docs/content/3.rendering/5.react.md +++ b/docs/content/3.rendering/5.react.md @@ -337,8 +337,8 @@ export default function App() { | `name` | `string` | `undefined` | Component name for debugging | | `autoUnwrap` | `boolean` | `true` | Automatically unwrap single block elements | | `autoClose` | `boolean` | `true` | Auto-close incomplete markdown syntax | -| `linkify` | `boolean` | `true` | Auto-convert URL-like text into links | -| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | +| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead | +| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | | [`plugins`](#plugins) | `ComarkPlugin[]` | `[]` | Array of plugins | | [`components`](#components) | `Record` | `{}` | Custom React component mappings | | [`transformNode`](#transformnode) | `NodeTransform \| NodeTransform[]` | `undefined` | Node transforms that run before the instance's own `transformNode` | diff --git a/docs/content/3.rendering/8.ansi.md b/docs/content/3.rendering/8.ansi.md index f21f432a0..5dfe9bd59 100644 --- a/docs/content/3.rendering/8.ansi.md +++ b/docs/content/3.rendering/8.ansi.md @@ -83,8 +83,8 @@ This is a bold statement with a link (https://example.com). | `width` | `number` | `80` | Terminal width for HR and code block headers | | `autoClose` | `boolean` | `true` | Close incomplete Markdown and components before parsing | | `autoUnwrap` | `boolean` | `true` | Remove a single paragraph wrapper inside components | -| `linkify` | `boolean` | `true` | Convert URL-like text into links | -| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | +| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) instead | +| `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | | `unwrap` | `boolean \| string \| string[]` | `false` | Remove selected wrapper tags from the parsed document | *Automatically set to `false` when the `NO_COLOR` env var is present. diff --git a/docs/content/4.plugins/0.defaults/linkify.md b/docs/content/4.plugins/0.defaults/linkify.md new file mode 100644 index 000000000..685fde93b --- /dev/null +++ b/docs/content/4.plugins/0.defaults/linkify.md @@ -0,0 +1,68 @@ +--- +title: Linkify +description: Plugin for converting URL-like text into links. +seo: + title: Linkify Plugin +navigation: + icon: i-lucide-link +links: + - label: Parse API + icon: i-lucide-file-code + to: /reference/parse + color: neutral + variant: soft +--- + +The `comark/plugins/linkify` plugin converts URLs such as `https://comark.dev` and emails such as `hi@comark.dev` into links, using [linkify-it](https://github.com/markdown-it/linkify-it). Domains without a scheme, such as `www.example.com`, are linked only with [`fuzzyLink`](#options). + +The plugin is **enabled by default** via `registerDefaultPlugins`. No installation or registration required. + +```typescript +import { parseMarkdown } from 'comark' + +await parseMarkdown('Read https://comark.dev') +``` + +Explicit registration is only needed when default plugins are disabled, or with `comark/core`. List it before markdown-it plugins that call `md.linkify.add()`: + +```typescript +import { parseMarkdown } from 'comark' +import linkify from 'comark/plugins/linkify' +import components from 'comark/plugins/components' + +const result = await parseMarkdown(content, { + registerDefaultPlugins: false, + plugins: [linkify(), components()], +}) +``` + +## Options + +`linkify()` accepts linkify-it's recognition options. Pass a configured `linkify()` in `plugins` to replace the default: + +```typescript +import { parseMarkdown } from 'comark' +import linkify from 'comark/plugins/linkify' + +await parseMarkdown('Visit www.example.com', { + plugins: [linkify({ fuzzyLink: true })], +}) +``` + +| Option | Type | Default | Description | +| --- | --- | --- | --- | +| `fuzzyLink` | `boolean` | `false` | Link domains without a scheme, such as `www.example.com` or `example.com`. Slower on long text | +| `fuzzyEmail` | `boolean` | `true` | Link emails without `mailto:` | +| `fuzzyIP` | `boolean` | `false` | Allow IP addresses in fuzzy links. Can match version numbers | +| `urlAuth` | `boolean` | `false` | Link URLs that contain credentials, such as `https://user:pass@example.com` | +| `tlds` | `string[]` | linkify-it's list | Top-level domains allowed in fuzzy links. Replaces the default list | +| `maxLength` | `number` | `10000` | Maximum link length | +| `'---'` | `boolean` | `false` | End a link at `---`, treating it as a long dash | + +::note +Before linkify-it 6, Comark linked `www.example.com` and `user:pass@` URLs by default. Pass `linkify({ fuzzyLink: true, urlAuth: true })` to keep that behavior. +:: + +::warning +The `linkify` parser option is **deprecated**. It logs a warning and will be removed in a future major version. Replace `linkify: false` with `registerDefaultPlugins: false`, then register only the default plugins you need. +:: diff --git a/docs/content/4.plugins/index.md b/docs/content/4.plugins/index.md index 82c0f9f91..93d7acb3c 100644 --- a/docs/content/4.plugins/index.md +++ b/docs/content/4.plugins/index.md @@ -13,6 +13,10 @@ All Comark plugins are part of the core `comark` package, while optional renderi These plugins are **enabled by default** whenever you call `parseMarkdown()` or `createMarkdownParser()` (or a framework `` component). You do not need to install or register them. ::card-group{cols="2"} + ::card{icon="i-lucide-link" title="Linkify" to="/plugins/defaults/linkify"} + Convert URL-like text into links + :: + ::card{icon="i-lucide-file-spreadsheet" title="Frontmatter" to="/plugins/defaults/frontmatter"} Parse a leading YAML frontmatter block into `tree.frontmatter` :: @@ -49,7 +53,7 @@ Turn them all off with `registerDefaultPlugins: false`: ```typescript import { parseMarkdown } from 'comark' -// Plain markdown only β€” no components, attributes, HTML, alerts, or task lists +// Plain markdown only β€” no autolinks, components, attributes, HTML, alerts, or task lists const result = await parseMarkdown(content, { registerDefaultPlugins: false, }) diff --git a/docs/content/5.reference/1.parse.md b/docs/content/5.reference/1.parse.md index 3dc5df46e..1254d31f0 100644 --- a/docs/content/5.reference/1.parse.md +++ b/docs/content/5.reference/1.parse.md @@ -367,7 +367,7 @@ console.timeEnd('createMarkdownParser x1000') Use `comark/core` when you want to choose every plugin yourself and keep the default plugins out of your bundle. It accepts the same options as `comark`, with two differences: -- Only the plugins in `plugins` run. `registerDefaultPlugins` is not accepted. +- Only the plugins in `plugins` run. `registerDefaultPlugins` is not accepted; add [`linkify()`](/plugins/defaults/linkify) to link bare URLs. - `autoClose` is a function or `undefined` (the default, which skips auto-closing). Pass `autoCloseMarkdown` from `comark/auto-close` to opt in. ```typescript [core.ts] @@ -395,9 +395,9 @@ Both `parseMarkdown()` and `createMarkdownParser()` accept the same `ParserOptio | `autoClose` | `boolean \| (markdown: string, streaming?: boolean) => string` | `true` | Auto-close incomplete markdown syntax, or use a custom completion function. `streaming` is `true` when the parse was called with `{ streaming: true }`. | | `unwrap` | `boolean \| string \| string[]` | `false` | Remove wrapper tags from the tree, hoisting their children (MDC `unwrap` behaviour). `true` unwraps `p`; a comma/whitespace-separated string or array unwraps the listed tags; `'*'` matches any tag. Tags apply sequentially (each descends one level), and adjacent text is merged into a single string. | -| `linkify` | `boolean` | `true` | Auto-convert URL-like text into links. Set `false` to disable | +| `linkify` | `boolean` | `true` | **Deprecated.** Use `registerDefaultPlugins: false` and register [`linkify()`](/plugins/defaults/linkify) only when needed. Still honored (over `registerDefaultPlugins`) and logs a warning | | `headingIds` | `boolean \| 'nested' \| 'flat'` | `true` | Auto-generate `id` attributes for `h1`–`h6` from visible heading text (not tag or component names). `true`/`'flat'` uses the heading's own text only (`install`); `'nested'` prefixes each id with its parent heading's id (`setup-install`); `false` disables auto ids. Unicode letters, marks, and numbers are kept (`## CafΓ©` β†’ `cafΓ©`); punctuation and symbols are dropped, and a heading that slugifies to nothing gets no id. Ids are unique per document: duplicates get a `-1`, `-2`, ... suffix (`options`, `options-1`, `options-2`). An explicit `id` attribute wins. See [Headings](/syntax/markdown#headings). | -| `registerDefaultPlugins` | `boolean` | `true` | Register the built-in default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). Set `false` to disable them. | +| `registerDefaultPlugins` | `boolean` | `true` | Register the built-in default plugins (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). Set `false` to disable them. | | `plugins` | `ComarkPlugin[]` | `[]` | Ordered plugins to run after the defaults. A same-name plugin replaces its default; duplicate explicit names keep the first instance. See [Default plugins](/plugins#default-plugins). | | `tracer` | `ComarkTracer` | `undefined` | Timing recorder for the parse pipeline β€” see [Timing the parse](#timing-the-parse) | diff --git a/docs/content/5.reference/3.reference.md b/docs/content/5.reference/3.reference.md index 035a61a6a..f04cc6266 100644 --- a/docs/content/5.reference/3.reference.md +++ b/docs/content/5.reference/3.reference.md @@ -358,7 +358,7 @@ interface ParserOptions { autoClose?: boolean | AutoCloseFunction // default: true unwrap?: boolean | string | string[] // strip top-level wrapper tags, e.g. 'p' (default: false) - linkify?: boolean // default: true + linkify?: boolean // deprecated: use registerDefaultPlugins: false + linkify() headingIds?: boolean | 'nested' | 'flat' // default: true ('flat') β€” slug from visible text; duplicates get -1, -2, … (keeps Unicode letters/numbers, omits symbol-only ids); explicit id wins registerDefaultPlugins?: boolean // default: true plugins?: ComarkPlugin[] diff --git a/packages/comark-angular/test/define-component.test.ts b/packages/comark-angular/test/define-component.test.ts index 7d36f8c86..8ef18c54b 100644 --- a/packages/comark-angular/test/define-component.test.ts +++ b/packages/comark-angular/test/define-component.test.ts @@ -40,7 +40,7 @@ describe('defineMarkdownComponent', () => { it('accepts parse options in config', () => { const Defined = defineMarkdownComponent({ autoClose: true, - linkify: true, + autoUnwrap: false, }) expect(Defined).toBeDefined() }) diff --git a/packages/comark-svelte/test/incremental-streaming.svelte.test.ts b/packages/comark-svelte/test/incremental-streaming.svelte.test.ts index 429655ce4..ba4f9b437 100644 --- a/packages/comark-svelte/test/incremental-streaming.svelte.test.ts +++ b/packages/comark-svelte/test/incremental-streaming.svelte.test.ts @@ -50,12 +50,12 @@ for (const [name, component] of [ component, value, streaming: true, - options: { linkify: false }, + options: { registerDefaultPlugins: false }, }) await expect.element(screen.getByText('Tail')).toBeInTheDocument() expect(screen.container.querySelector('a')).toBeNull() - await screen.rerender({ options: { linkify: true } }) + await screen.rerender({ options: { registerDefaultPlugins: true } }) await expect.element(screen.getByRole('link')).toHaveAttribute('href', 'https://example.com') const plugin: ComarkPlugin = { diff --git a/packages/comark/package.json b/packages/comark/package.json index 1ffa91608..c6e95af4e 100644 --- a/packages/comark/package.json +++ b/packages/comark/package.json @@ -81,7 +81,6 @@ "devDependencies": { "@json-render/core": "catalog:", "@shikijs/twoslash": "catalog:", - "@types/linkify-it": "catalog:", "@types/markdown-it": "catalog:", "entities": "catalog:", "github-slugger": "catalog:", diff --git a/packages/comark/src/core.ts b/packages/comark/src/core.ts index fc1c567f7..e7cdc772f 100644 --- a/packages/comark/src/core.ts +++ b/packages/comark/src/core.ts @@ -12,7 +12,6 @@ import type { ParserCoreOptions, } from './types.ts' import MarkdownExit, { type Token } from 'markdown-exit/core' -import type LinkifyIt from 'linkify-it' import { applyAutoUnwrap, extractReusableNodes } from './internal/parse/utils.ts' import { applyUnwrap, resolveUnwrapTags } from './internal/parse/unwrap.ts' import { createSerializedTask } from './utils/helpers.ts' @@ -32,43 +31,7 @@ export type * from './types.ts' const MAX_SHARED_PARSERS = 32 let nextPluginId = 0 const pluginIds = new WeakMap() -const sharedParsers = new Map() - -interface SharedParser { - md: MarkdownExit - // With `linkify`, settles once linkify-it is loaded and the markdown-it plugins are installed. - ready?: Promise - // Without `linkify`, set when a markdown-it plugin needs `md.linkify` to install. - needsLinkify?: boolean -} - -// Loaded on the first parse that needs it, so bundles without it skip linkify-it. -let linkifyModule: Promise | undefined - -// markdown-it plugins may configure `md.linkify` when installed, so they run after it exists. -// This also replaces the instance that the root `markdown-exit` entry gives every parser once -// something imports it. linkify-it 5 links `www.example.com` and `user:pass@` URLs by default; -// linkify-it 6 needs `fuzzyLink` for that, which made streaming chat text about 1.8x slower -// (markdown-it/linkify-it#126). -async function installLinkify(shared: SharedParser, mdPlugins: MarkdownExitPlugin[], linkify: boolean): Promise { - try { - const Linkify = await (linkifyModule ??= import('linkify-it').then((m) => m.default)) - // markdown-exit types this as linkify-it 6. It only calls `test`, `match` and `matchAtStart`, which 5 has too. - shared.md.linkify = new Linkify() as unknown as MarkdownExit['linkify'] - for (const fn of mdPlugins) shared.md.use(fn) - } catch (error) { - // Start over on the next parse: retry a failed load, such as a chunk fetch, and drop - // an instance that a throwing plugin left half set up. - linkifyModule = undefined - shared.md = createMarkdownExit(linkify) - shared.ready = undefined - throw error - } -} - -function createMarkdownExit(linkify: boolean): MarkdownExit { - return new MarkdownExit({ linkify }).enable(['table', 'strikethrough']) -} +const sharedParsers = new Map() /** * Creates a parser function without default plugins or a built-in auto-closer. @@ -102,33 +65,22 @@ export function createMarkdownParser pluginIds.get(fn) ?? (pluginIds.set(fn, nextPluginId), nextPluginId++)), - ].join(',') + const key = mdPlugins.map((fn) => pluginIds.get(fn) ?? (pluginIds.set(fn, nextPluginId), nextPluginId++)).join(',') - let shared = sharedParsers.get(key) - if (shared) { + let md = sharedParsers.get(key) + if (md) { // Touch for LRU: Map iteration order is insertion order. sharedParsers.delete(key) - sharedParsers.set(key, shared) + sharedParsers.set(key, md) } else { - shared = { md: createMarkdownExit(linkify) } - if (!linkify) { - try { - for (const fn of mdPlugins) shared.md.use(fn) - } catch (error) { - // `markdown-exit/core` has no `md.linkify`. Plugins that configure it get one on the first parse. - if (shared.md.linkify) throw error - shared = { md: createMarkdownExit(false), needsLinkify: true } - } - } + md = new MarkdownExit().enable(['table', 'strikethrough']) + // A plugin that throws leaves the instance uncached, so the next parser starts fresh. + for (const fn of mdPlugins) md.use(fn) if (sharedParsers.size >= MAX_SHARED_PARSERS) { const oldestKey = sharedParsers.keys().next().value if (oldestKey !== undefined) sharedParsers.delete(oldestKey) } - sharedParsers.set(key, shared) + sharedParsers.set(key, md) } let lastOutput: MarkdownDocument | null = null @@ -183,11 +135,8 @@ export function createMarkdownParser plugin.pre!(state)) } - // Same key, same plugin functions, so any parser sharing this instance can install them. - if (linkify || shared.needsLinkify) await (shared.ready ??= installLinkify(shared, mdPlugins, linkify)) - try { - state.tokens = withSpan(tracer, 'comark:tokenize', () => shared.md.parse(state.markdown, {})) + state.tokens = withSpan(tracer, 'comark:tokenize', () => md.parse(state.markdown, {})) } catch (e) { // in case of streaming, return the previous output if parsing fails // This is to avoid resetting the tree to an empty state on failure diff --git a/packages/comark/src/index.ts b/packages/comark/src/index.ts index cd655e8b3..258af7383 100644 --- a/packages/comark/src/index.ts +++ b/packages/comark/src/index.ts @@ -15,6 +15,7 @@ import taskList from './plugins/task-list.ts' import alert from './plugins/alert.ts' import html from './plugins/html.ts' import frontmatterPlugin from './plugins/frontmatter.ts' +import linkify from './plugins/linkify.ts' import { autoCloseMarkdown } from './auto-close.ts' import { createSerializedTask, dedupePlugins } from './utils/helpers.ts' import { noopTracer } from './utils/trace.ts' @@ -37,6 +38,8 @@ export type { ComarkContext, ComarkDocument, ComarkPatch } from './context.ts' // Re-export types export type * from './types.ts' +let warnedLinkifyOption = false + /** * Resolve public parser options into core options. * @@ -47,20 +50,31 @@ export type * from './types.ts' function resolveParserOptions[] = []>( options: ParserOptions ): ParserCoreOptions[]> { - const { autoClose = true, tracer = noopTracer } = options + const { autoClose = true, tracer = noopTracer, linkify: linkifyOption, ...rest } = options const userPlugins = options.plugins ?? [] - const defaultPlugins = - options.registerDefaultPlugins !== false - ? [frontmatterPlugin(), html(), alert(), taskList(), components(), attributes()] - : [] + if (linkifyOption !== undefined && !warnedLinkifyOption) { + warnedLinkifyOption = true + console.warn( + '[comark] `ParserOptions.linkify` is deprecated and will be removed in a future major version. ' + + 'Use `registerDefaultPlugins: false` and register `linkify()` from `comark/plugins/linkify` only when needed.' + ) + } + + const registerDefaults = options.registerDefaultPlugins !== false + // `linkify` comes first, so markdown-it plugins that configure `md.linkify` when installed find it. + // The deprecated `linkify` option still wins over `registerDefaultPlugins`, as it did before. + const defaultPlugins: ComarkPlugin[] = [ + ...((linkifyOption ?? registerDefaults) ? [linkify()] : []), + ...(registerDefaults ? [frontmatterPlugin(), html(), alert(), taskList(), components(), attributes()] : []), + ] const plugins = dedupePlugins(defaultPlugins, userPlugins) const hasPlugin = (name: string) => plugins.some((plugin) => plugin.name === name) const pluginAutoClose = Object.assign({}, ...plugins.map((p) => p.autoClose)) return { - ...options, + ...rest, plugins, tracer, autoClose: diff --git a/packages/comark/src/plugins/linkify.ts b/packages/comark/src/plugins/linkify.ts new file mode 100644 index 000000000..e2a32018f --- /dev/null +++ b/packages/comark/src/plugins/linkify.ts @@ -0,0 +1,44 @@ +/** + * Linkify plugin for Comark. + * + * Converts URLs with a scheme (`https://comark.dev`) and emails into links. + * Bare domains (`www.example.com`) need `fuzzyLink: true`. A default plugin in + * `comark` (off with `registerDefaultPlugins: false`); register it yourself + * with `comark/core`. + */ + +import { LinkifyIt, type LinkifyOptions } from 'linkify-it' +import type { MarkdownExit } from 'markdown-exit/core' +import type { MarkdownItPlugin } from '../types.ts' +import { defineComarkPlugin } from '../utils/helpers.ts' + +/** + * linkify-it recognition options. All default to linkify-it's own defaults: + * fuzzy links, fuzzy IPs and URL credentials off; fuzzy emails on. + */ +export type LinkifyPluginOptions = LinkifyOptions + +// Parsers share a markdown-exit instance only when their markdown-it plugin functions are the +// same, so equal options must map to the same function rather than a fresh closure per call. +const markdownItPlugins = new Map() + +function markdownItLinkify(options: LinkifyPluginOptions): MarkdownItPlugin { + const key = JSON.stringify(options) + let plugin = markdownItPlugins.get(key) + if (!plugin) { + plugin = ((md: MarkdownExit) => { + // Imported from `linkify-it` rather than the root `markdown-exit` entry, which would register + // a global linkifier for every parser. Fuzzy matching is opt-in: `fuzzyLink` made + // streaming chat text about 1.8x slower (markdown-it/linkify-it#126). + md.linkify = new LinkifyIt(options) + md.set({ linkify: true }) + }) as unknown as MarkdownItPlugin + markdownItPlugins.set(key, plugin) + } + return plugin +} + +export default defineComarkPlugin((options: LinkifyPluginOptions = {}) => ({ + name: 'linkify', + markdownItPlugins: [markdownItLinkify(options)], +})) diff --git a/packages/comark/src/types.ts b/packages/comark/src/types.ts index 60c591fcc..fd8dc3ce2 100644 --- a/packages/comark/src/types.ts +++ b/packages/comark/src/types.ts @@ -547,12 +547,6 @@ export interface ParserCoreOptions< */ autoClose?: AutoCloseFunction - /** - * Set `false` to disable autoconvert URL-like text to links. - * @default true - */ - linkify?: boolean - /** * How to auto-generate `id` attributes for `h1`–`h6` headings from their text content. * User-supplied `id` attributes are always preserved. @@ -617,9 +611,17 @@ export interface ParserOptions< */ autoClose?: boolean | AutoCloseFunction + /** + * @deprecated Use `registerDefaultPlugins: false` and register plugins explicitly + * (include `linkify()` from `comark/plugins/linkify` only when you need autolinks). + * Setting this option logs a deprecation warning. It still takes precedence over + * `registerDefaultPlugins`: `false` skips the default linkify plugin, `true` keeps it. + */ + linkify?: boolean + /** * Whether to register the built-in default plugins - * (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). + * (`linkify`, `frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`). * Set `false` to parse plain markdown with only the plugins listed in `plugins`. * Without the components/attributes plugins, `autoClose` skips component fences and attribute braces. * @default true diff --git a/packages/comark/test/linkify-retry.test.ts b/packages/comark/test/linkify-retry.test.ts index b3408c021..87d1042c9 100644 --- a/packages/comark/test/linkify-retry.test.ts +++ b/packages/comark/test/linkify-retry.test.ts @@ -1,27 +1,9 @@ -import { describe, expect, it, vi } from 'vitest' +import { describe, expect, it } from 'vitest' import type { MarkdownItPlugin } from 'comark' import type { MarkdownExit } from 'markdown-exit/core' -import { createMarkdownParser, defineComarkPlugin } from '../src/parse' - -const load = vi.hoisted(() => ({ fail: true })) -vi.mock('linkify-it', async (importOriginal) => { - if (load.fail) { - load.fail = false - throw new Error('Failed to fetch dynamically imported module') - } - return importOriginal() -}) - -describe('linkify setup failure', () => { - it('retries the import on the next parse', async () => { - const parse = createMarkdownParser() - - await expect(parse('https://comark.dev')).rejects.toThrow() - const doc = await parse('https://comark.dev') - - expect(doc.nodes).toEqual([['p', {}, ['a', { href: 'https://comark.dev' }, 'https://comark.dev']]]) - }) +import { createMarkdownParser, defineComarkPlugin } from '../src/index' +describe('markdown-it plugin setup failure', () => { it('installs plugins on a fresh instance after a plugin throws', async () => { let installs = 0 let runs = 0 @@ -36,10 +18,10 @@ describe('linkify setup failure', () => { }) as unknown as MarkdownItPlugin, ], })) - const parse = createMarkdownParser({ plugins: [flaky()] }) + const plugin = flaky() - await expect(parse('text')).rejects.toThrow('plugin failed') - await parse('text') + expect(() => createMarkdownParser({ plugins: [plugin] })).toThrow('plugin failed') + await createMarkdownParser({ plugins: [plugin] })('text') // The rule from the failed install is gone, so it runs once. expect(runs).toBe(1) diff --git a/packages/comark/test/linkify-root-entry.test.ts b/packages/comark/test/linkify-root-entry.test.ts index 0504d94d1..b99920a1d 100644 --- a/packages/comark/test/linkify-root-entry.test.ts +++ b/packages/comark/test/linkify-root-entry.test.ts @@ -1,22 +1,26 @@ import { describe, expect, it } from 'vitest' -import { createMarkdownParser } from '../src/parse' +import { createMarkdownParser } from '../src/index' +import linkify from '../src/plugins/linkify' // The root `markdown-exit` entry registers a plain LinkifyIt factory for every // instance, so it runs in its own file to keep that global out of other tests. describe('linkify with the markdown-exit root entry loaded', () => { - it('still links bare domains and URLs with credentials', async () => { + it('still uses the plugin options and links nothing without the plugin', async () => { await import('markdown-exit') + const source = 'www.example.com and https://comark.dev' - const doc = await createMarkdownParser()('www.example.com and https://user:pw@example.com/a') + const fuzzy = await createMarkdownParser({ plugins: [linkify({ fuzzyLink: true })] })(source) + const plain = await createMarkdownParser({ registerDefaultPlugins: false })(source) - expect(doc.nodes).toEqual([ + expect(fuzzy.nodes).toEqual([ [ 'p', {}, ['a', { href: 'http://www.example.com' }, 'www.example.com'], ' and ', - ['a', { href: 'https://user:pw@example.com/a' }, 'https://user:pw@example.com/a'], + ['a', { href: 'https://comark.dev' }, 'https://comark.dev'], ], ]) + expect(plain.nodes).toEqual([['p', {}, source]]) }) }) diff --git a/packages/comark/test/linkify.test.ts b/packages/comark/test/linkify.test.ts index db2acff0e..bbd5781ae 100644 --- a/packages/comark/test/linkify.test.ts +++ b/packages/comark/test/linkify.test.ts @@ -1,24 +1,33 @@ -import { execFileSync } from 'node:child_process' -import { describe, expect, it, vi } from 'vitest' +import { afterEach, describe, expect, it, vi } from 'vitest' import type { MarkdownItPlugin } from 'comark' import type { MarkdownExit } from 'markdown-exit/core' -import { createMarkdownParser, defineComarkPlugin, parseMarkdown } from '../src/parse' - -const linkifiers = vi.hoisted(() => ({ created: 0 })) -vi.mock('linkify-it', async (importOriginal) => { - const { default: LinkifyIt } = await importOriginal() - class CountingLinkifyIt extends LinkifyIt { - constructor(...args: ConstructorParameters) { - super(...args) - linkifiers.created++ - } - } - return { default: CountingLinkifyIt } -}) +import { createMarkdownParser, defineComarkPlugin, parseMarkdown } from '../src/index' +import { createMarkdownParser as createCoreMarkdownParser } from '../src/core' +import linkify from '../src/plugins/linkify' + +const link = ['a', { href: 'https://comark.dev' }, 'https://comark.dev'] describe('linkify', () => { - it('links bare domains and URLs with credentials', async () => { - const doc = await parseMarkdown('www.example.com and https://user:pw@example.com/a') + afterEach(() => { + vi.restoreAllMocks() + }) + + it('links scheme URLs and emails, not bare domains, by default', async () => { + const doc = await parseMarkdown('https://comark.dev, hi@comark.dev and www.example.com') + expect(doc.nodes).toEqual([ + ['p', {}, link, ', ', ['a', { href: 'mailto:hi@comark.dev' }, 'hi@comark.dev'], ' and www.example.com'], + ]) + }) + + it('passes options to linkify-it, so fuzzy links and URL credentials are opt-in', async () => { + const source = 'www.example.com and https://user:pw@example.com/a' + const parse = createMarkdownParser({ + registerDefaultPlugins: false, + plugins: [linkify({ fuzzyLink: true, urlAuth: true })], + }) + + const doc = await parse(source) + expect(doc.nodes).toEqual([ [ 'p', @@ -30,7 +39,13 @@ describe('linkify', () => { ]) }) - it('gives markdown-it plugins md.linkify when they are installed, also with linkify off', async () => { + it('replaces the default plugin with a configured one', async () => { + const doc = await createMarkdownParser({ plugins: [linkify({ fuzzyLink: true })] })('www.example.com') + + expect(doc.nodes).toEqual([['p', {}, ['a', { href: 'http://www.example.com' }, 'www.example.com']]]) + }) + + it('gives markdown-it plugins md.linkify when they are installed', async () => { // Mention plugins register a linkify schema when installed. const mention = defineComarkPlugin(() => ({ name: 'linkify-mention', @@ -49,50 +64,71 @@ describe('linkify', () => { const doc = await createMarkdownParser({ plugins: [mention()] })('hi @comark') expect(doc.nodes).toEqual([['p', {}, 'hi ', ['a', { href: 'https://github.com/comark' }, '@comark']]]) + }) - const plain = await createMarkdownParser({ linkify: false, plugins: [mention()] })('hi @comark') - expect(plain.nodes).toEqual([['p', {}, 'hi @comark']]) + it('is a default plugin', async () => { + const plain = await createMarkdownParser({ registerDefaultPlugins: false })('https://comark.dev') + const linked = await createMarkdownParser({ registerDefaultPlugins: false, plugins: [linkify()] })( + 'https://comark.dev' + ) + + expect(plain.nodes).toEqual([['p', {}, 'https://comark.dev']]) + expect(linked.nodes).toEqual([['p', {}, link]]) }) - it('creates one linkifier when a new parser runs several parses at once', async () => { - // A markdown-it plugin no other parser uses keeps this parser out of the shared cache. - const fresh = defineComarkPlugin(() => ({ - name: 'linkify-concurrent', - markdownItPlugins: [(() => {}) as unknown as MarkdownItPlugin], - })) - const parse = createMarkdownParser({ plugins: [fresh()] }) - const before = linkifiers.created + it('keeps parsers with and without linkify independent', async () => { + const source = 'See https://comark.dev' + const linkedNodes = [['p', {}, 'See ', link]] + const plainNodes = [['p', {}, source]] - const docs = await Promise.all(Array.from({ length: 10 }, () => parse('See https://comark.dev'))) + const withLinkify = createMarkdownParser({ registerDefaultPlugins: false, plugins: [linkify()] }) + const withoutLinkify = createMarkdownParser({ registerDefaultPlugins: false }) - expect(linkifiers.created - before).toBe(1) - expect(docs[9].nodes).toEqual([['p', {}, 'See ', ['a', { href: 'https://comark.dev' }, 'https://comark.dev']]]) + // Interleave, so state leaking between the two parsers in either direction would show up. + const [linked, plain] = await Promise.all([withLinkify(source), withoutLinkify(source)]) + const plainAgain = await withoutLinkify(source) + const linkedAgain = await withLinkify(source) + + expect(linked.nodes).toEqual(linkedNodes) + expect(linkedAgain.nodes).toEqual(linkedNodes) + expect(plain.nodes).toEqual(plainNodes) + expect(plainAgain.nodes).toEqual(plainNodes) }) - it('loads linkify-it only for parsers with linkify enabled', () => { - const output = execFileSync( - process.execPath, - [ - '--input-type=module', - '-e', - ` - import { registerHooks } from 'node:module' - const loaded = [] - registerHooks({ - load(url, context, next) { - if (url.includes('/linkify-it/')) loaded.push(url) - return next(url, context) - }, - }) - const { createMarkdownParser } = await import('comark') - await createMarkdownParser({ linkify: false })('https://comark.dev') - const before = loaded.length - await createMarkdownParser()('https://comark.dev') - console.log(before, loaded.length > 0) - `, - ], - { cwd: import.meta.dirname, encoding: 'utf8' } - ) - expect(output.trim()).toBe('0 true') + it('links with comark/core only when the plugin is registered', async () => { + const plain = await createCoreMarkdownParser()('https://comark.dev') + const linked = await createCoreMarkdownParser({ plugins: [linkify()] })('https://comark.dev') + + expect(plain.nodes).toEqual([['p', {}, 'https://comark.dev']]) + expect(linked.nodes).toEqual([['p', {}, link]]) + }) + + describe('deprecated linkify option', () => { + it('still controls the default plugin, over registerDefaultPlugins', async () => { + vi.spyOn(console, 'warn').mockImplementation(() => {}) + + const off = await createMarkdownParser({ linkify: false })('https://comark.dev') + const on = await createMarkdownParser({ registerDefaultPlugins: false, linkify: true })('https://comark.dev') + const explicit = await createMarkdownParser({ linkify: false, plugins: [linkify()] })('https://comark.dev') + + expect(off.nodes).toEqual([['p', {}, 'https://comark.dev']]) + expect(on.nodes).toEqual([['p', {}, link]]) + expect(explicit.nodes).toEqual([['p', {}, link]]) + }) + + it('warns at most once per process', async () => { + // A fresh module copy, so a warning from another test does not count. + vi.resetModules() + const { createMarkdownParser: create } = await import('../src/index') + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}) + + create() + expect(warn).not.toHaveBeenCalled() + + create({ linkify: false }) + create({ linkify: true }) + expect(warn).toHaveBeenCalledOnce() + expect(warn.mock.calls[0]![0]).toContain('`ParserOptions.linkify` is deprecated') + }) }) }) diff --git a/packages/comark/test/parser-sharing.test.ts b/packages/comark/test/parser-sharing.test.ts index 8f9bc4e20..b82c9e877 100644 --- a/packages/comark/test/parser-sharing.test.ts +++ b/packages/comark/test/parser-sharing.test.ts @@ -2,11 +2,11 @@ import { describe, expect, it } from 'vitest' import { createMarkdownParser, defineComarkPlugin } from 'comark' import type { MarkdownItPlugin } from 'comark' import binding from '../src/plugins/binding' +import linkify from '../src/plugins/linkify' // The shared instance is internal, so it is observed through the public API: a // markdown-it plugin function runs once per instance, so counting how often it -// is registered counts the instances that were built. With linkify on, plugins -// install on the first parse, so these parsers turn it off to install at build. +// is registered counts the instances that were built. let stableUses = 0 const stableMdPlugin = (() => { stableUses++ @@ -33,7 +33,7 @@ describe('parser sharing', () => { const before = stableUses for (let i = 0; i < 20; i++) { - createMarkdownParser({ linkify: false, plugins: [plugin] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [plugin] }) } expect(stableUses - before).toBe(1) @@ -43,7 +43,7 @@ describe('parser sharing', () => { const before = closureUses for (let i = 0; i < 5; i++) { - createMarkdownParser({ linkify: false, plugins: [closurePlugin()] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [closurePlugin()] }) } expect(closureUses - before).toBe(5) @@ -69,35 +69,47 @@ describe('parser sharing', () => { markdownItPlugins: [oldestMdPlugin], }))() - createMarkdownParser({ linkify: false, plugins: [markedPlugin] }) - createMarkdownParser({ linkify: false, plugins: [oldestPlugin] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [markedPlugin] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [oldestPlugin] }) // Capacity is 32. Keep both named entries in the cache, then refresh // markedPlugin before inserting one more key so only oldestPlugin ages out. for (let i = 0; i < 30; i++) { - createMarkdownParser({ linkify: false, plugins: [closurePlugin()] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [closurePlugin()] }) } expect(markedUses).toBe(1) expect(oldestUses).toBe(1) - createMarkdownParser({ linkify: false, plugins: [markedPlugin] }) - createMarkdownParser({ linkify: false, plugins: [closurePlugin()] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [markedPlugin] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [closurePlugin()] }) - createMarkdownParser({ linkify: false, plugins: [oldestPlugin] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [oldestPlugin] }) expect(oldestUses).toBe(2) - createMarkdownParser({ linkify: false, plugins: [markedPlugin] }) + createMarkdownParser({ registerDefaultPlugins: false, plugins: [markedPlugin] }) expect(markedUses).toBe(1) }) - it('does not share an instance between linkify settings', async () => { - const withLinkify = await createMarkdownParser({ linkify: true })('See https://comark.dev for more') - const withoutLinkify = await createMarkdownParser({ linkify: false })('See https://comark.dev for more') + it('does not share an instance between parsers with and without linkify', async () => { + const withLinkify = await createMarkdownParser({ registerDefaultPlugins: false, plugins: [linkify()] })( + 'See https://comark.dev for more' + ) + const withoutLinkify = await createMarkdownParser({ registerDefaultPlugins: false })( + 'See https://comark.dev for more' + ) expect(JSON.stringify(withLinkify.nodes)).toContain('"a"') expect(JSON.stringify(withoutLinkify.nodes)).not.toContain('"a"') }) + it('shares an instance between linkify() calls with equal options', () => { + const a = linkify({ fuzzyLink: true }) + const b = linkify({ fuzzyLink: true }) + + expect(a.markdownItPlugins![0]).toBe(b.markdownItPlugins![0]) + expect(linkify().markdownItPlugins![0]).not.toBe(a.markdownItPlugins![0]) + }) + it('keeps streaming state on the parser across another parser use', async () => { const streaming = createMarkdownParser() const other = createMarkdownParser() diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 662ea4739..d0c886d87 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -257,9 +257,6 @@ catalogs: '@types/json-schema': specifier: ^7.0.15 version: 7.0.15 - '@types/linkify-it': - specifier: ^5.0.0 - version: 5.0.0 '@types/markdown-it': specifier: ^14.2.0 version: 14.2.0 @@ -345,8 +342,8 @@ catalogs: specifier: ^0.19.1 version: 0.19.1 linkify-it: - specifier: ^5.0.0 - version: 5.0.2 + specifier: ^6.0.0 + version: 6.1.0 markdown-exit: specifier: 2.1.0 version: 2.1.0 @@ -1451,7 +1448,7 @@ importers: version: 0.19.1 linkify-it: specifier: 'catalog:' - version: 5.0.2 + version: 6.1.0 markdown-exit: specifier: 'catalog:' version: 2.1.0 @@ -1465,9 +1462,6 @@ importers: '@shikijs/twoslash': specifier: 'catalog:' version: 4.5.0(supports-color@10.2.2)(typescript@6.0.3) - '@types/linkify-it': - specifier: 'catalog:' - version: 5.0.0 '@types/markdown-it': specifier: 'catalog:' version: 14.2.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 68a06eeee..f7f9a7f46 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -57,7 +57,6 @@ catalog: # Types "@types/json-schema": ^7.0.15 - "@types/linkify-it": ^5.0.0 "@types/markdown-it": ^14.2.0 "@types/node": ^26.6.6 "@types/react": ^19.3.0 @@ -98,7 +97,7 @@ catalog: hast-util-to-string: ^3.0.1 js-yaml: ^5.5.0 katex: ^0.19.1 - linkify-it: ^5.0.0 + linkify-it: ^6.0.0 markdown-exit: 2.1.0 "markdown-it": ^15.0.3 markdown-it-math: ^6.1.0 From 4d86fd9d5e7ba342252094e52cf591aafd6a1af0 Mon Sep 17 00:00:00 2001 From: Farnabaz Date: Thu, 5 Nov 2026 15:33:05 +0100 Subject: [PATCH 13/15] Update bundle.test.ts --- test/bundle.test.ts | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test/bundle.test.ts b/test/bundle.test.ts index a95c7fc9f..60b2c1f2b 100644 --- a/test/bundle.test.ts +++ b/test/bundle.test.ts @@ -60,14 +60,14 @@ describe('package bundle size', { timeout: 60_000 }, () => { expect(report).toMatchInlineSnapshot(` { - "@comark/angular": "59.9k (77 files)", - "@comark/ansi": "38.8k (103 files)", - "@comark/html": "17.1k (63 files)", - "@comark/nuxt": "13.4k (63 files)", - "@comark/react": "42.7k (81 files)", - "@comark/svelte": "50.1k (89 files)", - "@comark/vue": "60.1k (85 files)", - "comark": "416k (163 files)", + "@comark/angular": "60.1k (79 files)", + "@comark/ansi": "39.0k (105 files)", + "@comark/html": "17.3k (65 files)", + "@comark/nuxt": "13.5k (65 files)", + "@comark/react": "42.9k (83 files)", + "@comark/svelte": "50.3k (91 files)", + "@comark/vue": "60.2k (87 files)", + "comark": "422k (167 files)", } `) }) From 4c6327656709d43b93934a1fd58dd762eafd114b Mon Sep 17 00:00:00 2001 From: Farnabaz Date: Thu, 5 Nov 2026 15:54:12 +0100 Subject: [PATCH 14/15] chore: drop entities dev dependency --- packages/comark/package.json | 2 +- packages/comark/test/text-content.test.ts | 2 +- pnpm-lock.yaml | 6 ------ pnpm-workspace.yaml | 2 +- 4 files changed, 3 insertions(+), 9 deletions(-) diff --git a/packages/comark/package.json b/packages/comark/package.json index c6e95af4e..ab55afc82 100644 --- a/packages/comark/package.json +++ b/packages/comark/package.json @@ -82,7 +82,7 @@ "@json-render/core": "catalog:", "@shikijs/twoslash": "catalog:", "@types/markdown-it": "catalog:", - "entities": "catalog:", + "github-slugger": "catalog:", "hast-util-to-string": "catalog:", "minimark": "catalog:", diff --git a/packages/comark/test/text-content.test.ts b/packages/comark/test/text-content.test.ts index c1a95cf77..36ff926d1 100644 --- a/packages/comark/test/text-content.test.ts +++ b/packages/comark/test/text-content.test.ts @@ -1,6 +1,6 @@ import { describe, expect, it } from 'vitest' -import { decodeHTML } from 'entities' import type { Node } from 'comark' +import { decodeHTMLAttribute as decodeHTML } from '../src/internal/entities' import { textContent } from '../src/utils' describe('textContent', () => { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d0c886d87..6288a186f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -326,9 +326,6 @@ catalogs: comark-linter: specifier: ^0.7.6 version: 0.7.6 - entities: - specifier: ^8.1.0 - version: 8.1.0 github-slugger: specifier: ^2.0.0 version: 2.0.0 @@ -1465,9 +1462,6 @@ importers: '@types/markdown-it': specifier: 'catalog:' version: 14.2.0 - entities: - specifier: 'catalog:' - version: 8.1.0 github-slugger: specifier: 'catalog:' version: 2.0.0 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index f7f9a7f46..e7f69da5c 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -92,7 +92,7 @@ catalog: # Core comark dependencies character-entities: ^2.0.2 character-entities-legacy: ^3.0.0 - entities: ^8.1.0 + github-slugger: ^2.0.0 hast-util-to-string: ^3.0.1 js-yaml: ^5.5.0 From 01c7c44b676af64575f1ffe8476c4173cdd397a6 Mon Sep 17 00:00:00 2001 From: Farnabaz Date: Thu, 5 Nov 2026 15:55:14 +0100 Subject: [PATCH 15/15] Update package.json --- packages/comark/package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/packages/comark/package.json b/packages/comark/package.json index ab55afc82..7b345336a 100644 --- a/packages/comark/package.json +++ b/packages/comark/package.json @@ -82,7 +82,6 @@ "@json-render/core": "catalog:", "@shikijs/twoslash": "catalog:", "@types/markdown-it": "catalog:", - "github-slugger": "catalog:", "hast-util-to-string": "catalog:", "minimark": "catalog:",