From 97e5ae7b31ef5124cae0e76119d0a968e093bb52 Mon Sep 17 00:00:00 2001 From: onmax Date: Thu, 5 Nov 2026 23:50:22 +0100 Subject: [PATCH 1/5] perf(yaml)!: load YAML only when a document needs it `renderMarkdown` loads the YAML serializer only for documents with frontmatter or YAML component attributes. The frontmatter plugin loads the YAML parser only when the document starts with `---`. BREAKING CHANGE: `parseFrontmatter` is no longer exported from `comark`, and `renderFrontmatter` is no longer exported from `comark/render`. Import both from `comark/frontmatter`. --- AGENTS.md | 11 +++- .../4.plugins/0.defaults/frontmatter.md | 2 +- docs/content/5.reference/1.parse.md | 3 +- packages/comark/package.json | 1 + packages/comark/src/frontmatter.ts | 16 +++++ packages/comark/src/index.ts | 3 - .../src/internal/{ => parse}/frontmatter.ts | 26 +------- packages/comark/src/internal/parse/yaml.ts | 16 +++++ .../src/internal/stringify/attributes.ts | 5 +- .../src/internal/stringify/frontmatter.ts | 28 +++++++++ .../src/internal/stringify/handlers/mdc.ts | 2 +- .../src/internal/{ => stringify}/yaml.ts | 17 +----- packages/comark/src/plugins/components.ts | 2 +- packages/comark/src/plugins/frontmatter.ts | 8 ++- packages/comark/src/plugins/json-render.ts | 2 +- packages/comark/src/render/index.ts | 10 ++-- packages/comark/test/frontmatter.test.ts | 2 +- packages/comark/test/index.test.ts | 2 +- packages/comark/test/yaml-lazy-load.test.ts | 60 +++++++++++++++++++ packages/comark/test/yaml.test.ts | 2 +- 20 files changed, 154 insertions(+), 64 deletions(-) create mode 100644 packages/comark/src/frontmatter.ts rename packages/comark/src/internal/{ => parse}/frontmatter.ts (54%) create mode 100644 packages/comark/src/internal/parse/yaml.ts create mode 100644 packages/comark/src/internal/stringify/frontmatter.ts rename packages/comark/src/internal/{ => stringify}/yaml.ts (66%) create mode 100644 packages/comark/test/yaml-lazy-load.test.ts diff --git a/AGENTS.md b/AGENTS.md index 20375c20b..83464312b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,6 +59,7 @@ packages/comark/ │ ├── core.ts # Parser pipeline with no default plugins (comark/core) │ ├── auto-close.ts # autoCloseMarkdown() (comark/auto-close) │ ├── context.ts # Live renderer context: ComarkContext, ComarkDocument, ComarkPatch (comark/context) +│ ├── frontmatter.ts # parseFrontmatter() / renderFrontmatter() (comark/frontmatter) │ ├── render/ │ │ ├── index.ts # String rendering: renderMarkdown() (renderHtmlFromDocument() moved to @comark/html) │ │ └── html.ts # HTML-only renderer (comark/render/html) @@ -98,12 +99,12 @@ packages/comark/ │ │ └── caret.ts # Caret utilities for streaming │ └── internal/ # Internal implementation (not exported) │ ├── shiki.ts # Shared Shiki runtime used by both entry points -│ ├── frontmatter.ts # parseFrontmatter() / renderFrontmatter() │ ├── heading-id.ts # Auto heading id generation (shared by parser + stringifier) -│ ├── yaml.ts # YAML helpers │ ├── sanitize.ts # Component props validation and frontmatter sanitization │ ├── parse/ # Parsing pipeline │ │ ├── token-processor.ts # markdown-exit tokens → document nodes +│ │ ├── frontmatter.ts # parseFrontmatter() +│ │ ├── yaml.ts # parseYaml() │ │ ├── auto-close/ # Self-healing for incomplete markdown │ │ ├── html/ # HTML block/inline rules │ │ ├── syntax/ # Component syntax scanners (props, brackets, block params) @@ -111,7 +112,7 @@ packages/comark/ │ │ ├── indent.ts # Dedent of outdented component children │ │ ├── unwrap.ts # `unwrap` option │ │ └── auto-unwrap.ts # `autoUnwrap` option -│ └── stringify/ # AST → markdown string rendering (handlers/ per tag; transform-node.ts runs `transformNode`) +│ └── stringify/ # AST → markdown string rendering (handlers/ per tag; transform-node.ts runs `transformNode`; frontmatter.ts and yaml.ts load only when a document needs YAML) ├── SPEC/ # Behavioral spec fixtures (CommonMark, GFM, HTML, COMARK, auto-close.md) ├── test/ # Vitest test files ├── package.json @@ -131,6 +132,7 @@ packages/comark/ "./core": "./dist/core.js", "./auto-close": "./dist/auto-close.js", "./context": "./dist/context.js", + "./frontmatter": "./dist/frontmatter.js", "./render": "./dist/render/index.js", "./render/html": "./dist/render/html.js" } @@ -483,6 +485,9 @@ import { parseMarkdown } from 'comark/parse' // deprecated alias of the root exp import { parseMarkdown } from 'comark/core' // no default plugins; autoClose is a function, not a boolean import { autoCloseMarkdown } from 'comark/auto-close' +// YAML frontmatter, without the parser or renderer +import { parseFrontmatter, renderFrontmatter } from 'comark/frontmatter' + // Live renderer context (patch a rendered document without re-parsing) import { createComarkContext } from 'comark' import { createComarkContext } from 'comark/context' diff --git a/docs/content/4.plugins/0.defaults/frontmatter.md b/docs/content/4.plugins/0.defaults/frontmatter.md index 6c1bc2006..43ed20584 100644 --- a/docs/content/4.plugins/0.defaults/frontmatter.md +++ b/docs/content/4.plugins/0.defaults/frontmatter.md @@ -77,7 +77,7 @@ const result = await parseMarkdown(content, { registerDefaultPlugins: false }) In the `pre` hook (before markdown-exit tokenization), the plugin: -1. Detects a leading `---` … `---` block via `parseFrontmatter` +1. Detects a leading `---` … `---` block via `parseFrontmatter` from `comark/frontmatter`. The YAML parser loads only when the document starts with `---` 2. Parses the YAML body into `state.frontmatter` 3. Strips the frontmatter from `state.markdown` 4. Adjusts `state.parsedLines` so later nodes get correct line numbers diff --git a/docs/content/5.reference/1.parse.md b/docs/content/5.reference/1.parse.md index 1254d31f0..c66d893f9 100644 --- a/docs/content/5.reference/1.parse.md +++ b/docs/content/5.reference/1.parse.md @@ -357,10 +357,11 @@ console.timeEnd('createMarkdownParser x1000') | Import | Contents | |--------|----------| -| `comark` | `parseMarkdown()`, `createMarkdownParser()`, `createSerializedMarkdownParser()` with the default plugins and auto-close, plus `autoCloseMarkdown()`, `createComarkContext()`, `defineComarkPlugin()`, `parseFrontmatter()` | +| `comark` | `parseMarkdown()`, `createMarkdownParser()`, `createSerializedMarkdownParser()` with the default plugins and auto-close, plus `autoCloseMarkdown()`, `createComarkContext()`, `defineComarkPlugin()` | | `comark/core` | The same three parser functions with no default plugins and no built-in auto-closer | | `comark/auto-close` | `autoCloseMarkdown()` and its placeholders, without the parser | | `comark/context` | `createComarkContext()` and the live-update types, without the parser | +| `comark/frontmatter` | `parseFrontmatter()` and `renderFrontmatter()`, without the parser or renderer | | `comark/parse` | **Deprecated.** Alias of `comark`. Import from `comark` instead | ### `comark/core` diff --git a/packages/comark/package.json b/packages/comark/package.json index b622bffae..fa74af755 100644 --- a/packages/comark/package.json +++ b/packages/comark/package.json @@ -55,6 +55,7 @@ "./core": "./dist/core.js", "./auto-close": "./dist/auto-close.js", "./context": "./dist/context.js", + "./frontmatter": "./dist/frontmatter.js", "./render": "./dist/render/index.js", "./render/html": "./dist/render/html.js" }, diff --git a/packages/comark/src/frontmatter.ts b/packages/comark/src/frontmatter.ts new file mode 100644 index 000000000..b3c167dc8 --- /dev/null +++ b/packages/comark/src/frontmatter.ts @@ -0,0 +1,16 @@ +/** + * Read and write YAML frontmatter without the parser or renderer. + * + * @example + * ```typescript + * import { parseFrontmatter, renderFrontmatter } from 'comark/frontmatter' + * + * const { content, data } = parseFrontmatter('---\ntitle: Hi\n---\n\n# Hello') + * // data → { title: 'Hi' }, content → '\n# Hello' + * + * renderFrontmatter({ title: 'Hi' }, '# Hello') + * // → '---\ntitle: Hi\n---\n\n# Hello' + * ``` + */ +export { parseFrontmatter } from './internal/parse/frontmatter.ts' +export { renderFrontmatter } from './internal/stringify/frontmatter.ts' diff --git a/packages/comark/src/index.ts b/packages/comark/src/index.ts index 258af7383..fc92b9843 100644 --- a/packages/comark/src/index.ts +++ b/packages/comark/src/index.ts @@ -25,9 +25,6 @@ import { createMarkdownParser as createCoreMarkdownParser } from './core.ts' export { autoCloseMarkdown, INCOMPLETE_LINK_PLACEHOLDER, INCOMPLETE_IMAGE_PLACEHOLDER } from './auto-close.ts' export type { AutoCloseOptions, LinkMode } from './auto-close.ts' -// Re-export frontmatter utilities -export { parseFrontmatter } from './internal/frontmatter.ts' - // Re-export plugin utilities export { defineComarkPlugin } from './utils/helpers.ts' diff --git a/packages/comark/src/internal/frontmatter.ts b/packages/comark/src/internal/parse/frontmatter.ts similarity index 54% rename from packages/comark/src/internal/frontmatter.ts rename to packages/comark/src/internal/parse/frontmatter.ts index 64d8a9195..cf9653158 100644 --- a/packages/comark/src/internal/frontmatter.ts +++ b/packages/comark/src/internal/parse/frontmatter.ts @@ -1,5 +1,4 @@ -import type { DumpOptions } from 'js-yaml' -import { parseYaml, stringifyYaml } from './yaml.ts' +import { parseYaml } from './yaml.ts' const FRONTMATTER_DELIMITER_DEFAULT = '---' const LF = '\n' @@ -31,26 +30,3 @@ export function parseFrontmatter(content: string) { frontmatterText: frontmatter, } } - -/** - * Render frontmatter to content - * @param data - The data to render - * @param content - The content to render - * @returns The rendered content - */ -export function renderFrontmatter( - data: Record | undefined | null, - content?: string, - yamlOptions?: DumpOptions -): string { - if (!data || Object.keys(data).length === 0) { - return content?.trim() || '' - } - - const fm = stringifyYaml(data, yamlOptions).trim() - if (content) { - return FRONTMATTER_DELIMITER_DEFAULT + LF + fm + LF + FRONTMATTER_DELIMITER_DEFAULT + LF + LF + content.trim() - } - - return fm -} diff --git a/packages/comark/src/internal/parse/yaml.ts b/packages/comark/src/internal/parse/yaml.ts new file mode 100644 index 000000000..95e22d968 --- /dev/null +++ b/packages/comark/src/internal/parse/yaml.ts @@ -0,0 +1,16 @@ +import { JSON_SCHEMA, loadAll, YAMLException } from 'js-yaml' + +/** + * Parse YAML content. + * + * @param content - The content to parse + * @returns The parsed data, or `undefined` when the content has no YAML document + */ +export function parseYaml(content: string): Record | undefined { + const documents = loadAll(content, { schema: JSON_SCHEMA }) as Record[] + // Preserve `load()`'s single-document guard rather than silently taking the first. + if (documents.length > 1) { + throw new YAMLException('expected a single document in the stream, but found more') + } + return documents[0] +} diff --git a/packages/comark/src/internal/stringify/attributes.ts b/packages/comark/src/internal/stringify/attributes.ts index 8233d1c27..4b79ad1d0 100644 --- a/packages/comark/src/internal/stringify/attributes.ts +++ b/packages/comark/src/internal/stringify/attributes.ts @@ -1,4 +1,3 @@ -import { stringifyYaml } from '../yaml.ts' import { pickFence } from './fence.ts' export { resolveAttributes, resolveAttribute } from './html-attributes.ts' @@ -128,7 +127,7 @@ function normalizeValue(value: unknown): unknown { * @param attributes - The attributes to stringify * @returns The stringified attributes */ -export function comarkYamlAttributes( +export async function comarkYamlAttributes( attributes: Record, style: 'frontmatter' | 'codeblock' = 'codeblock' ) { @@ -157,6 +156,8 @@ export function comarkYamlAttributes( }) ) + // The YAML serializer loads only when a component needs YAML attributes. + const { stringifyYaml } = await import('./yaml.ts') const yamlContent = stringifyYaml(normalized).trim() if (style === 'frontmatter') { diff --git a/packages/comark/src/internal/stringify/frontmatter.ts b/packages/comark/src/internal/stringify/frontmatter.ts new file mode 100644 index 000000000..72e7fcfa3 --- /dev/null +++ b/packages/comark/src/internal/stringify/frontmatter.ts @@ -0,0 +1,28 @@ +import type { DumpOptions } from 'js-yaml' +import { stringifyYaml } from './yaml.ts' + +const FRONTMATTER_DELIMITER_DEFAULT = '---' +const LF = '\n' + +/** + * Render frontmatter to content + * @param data - The data to render + * @param content - The content to render + * @returns The rendered content + */ +export function renderFrontmatter( + data: Record | undefined | null, + content?: string, + yamlOptions?: DumpOptions +): string { + if (!data || Object.keys(data).length === 0) { + return content?.trim() || '' + } + + const fm = stringifyYaml(data, yamlOptions).trim() + if (content) { + return FRONTMATTER_DELIMITER_DEFAULT + LF + fm + LF + FRONTMATTER_DELIMITER_DEFAULT + LF + LF + content.trim() + } + + return fm +} diff --git a/packages/comark/src/internal/stringify/handlers/mdc.ts b/packages/comark/src/internal/stringify/handlers/mdc.ts index 12335b72d..1763e04ac 100644 --- a/packages/comark/src/internal/stringify/handlers/mdc.ts +++ b/packages/comark/src/internal/stringify/handlers/mdc.ts @@ -62,7 +62,7 @@ export async function mdc(node: ElementNode, state: State, parent?: ElementNode) const maxInlineAttributes = state.context.maxInlineAttributes ?? 3 const useYaml = hasObjectAttributes || maxInlineAttributes === 0 || attributeEntries.length > maxInlineAttributes if (useYaml) { - const yamlAttrs = comarkYamlAttributes(attributes, state.context.blockAttributesStyle) + const yamlAttrs = await comarkYamlAttributes(attributes, state.context.blockAttributesStyle) result = `${fence}${tag}\n${yamlAttrs}${content ? `\n${content}` : ''}\n${fence}` + state.context.blockSeparator } else { result = `${fence}${tag}${attrs}${content ? `\n${content}` : ''}\n${fence}` + state.context.blockSeparator diff --git a/packages/comark/src/internal/yaml.ts b/packages/comark/src/internal/stringify/yaml.ts similarity index 66% rename from packages/comark/src/internal/yaml.ts rename to packages/comark/src/internal/stringify/yaml.ts index 95ad040dc..8db48bd4d 100644 --- a/packages/comark/src/internal/yaml.ts +++ b/packages/comark/src/internal/stringify/yaml.ts @@ -1,19 +1,4 @@ -import { dump, JSON_SCHEMA, loadAll, YAMLException, type DumpOptions } from 'js-yaml' - -/** - * Parse YAML content. - * - * @param content - The content to parse - * @returns The parsed data, or `undefined` when the content has no YAML document - */ -export function parseYaml(content: string): Record | undefined { - const documents = loadAll(content, { schema: JSON_SCHEMA }) as Record[] - // Preserve `load()`'s single-document guard rather than silently taking the first. - if (documents.length > 1) { - throw new YAMLException('expected a single document in the stream, but found more') - } - return documents[0] -} +import { dump, type DumpOptions } from 'js-yaml' /** * Stringify YAML data diff --git a/packages/comark/src/plugins/components.ts b/packages/comark/src/plugins/components.ts index 9e2abcf9c..6e9d99e6e 100644 --- a/packages/comark/src/plugins/components.ts +++ b/packages/comark/src/plugins/components.ts @@ -13,7 +13,7 @@ import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from '../utils/helpers.ts' import { findClosingBracket, parseBracketContent } from '../internal/parse/syntax/brackets.ts' import { parseBlockParams } from '../internal/parse/syntax/block-params.ts' -import { parseYaml } from '../internal/yaml.ts' +import { parseYaml } from '../internal/parse/yaml.ts' import { tokenizeDedented } from '../internal/parse/indent.ts' /** diff --git a/packages/comark/src/plugins/frontmatter.ts b/packages/comark/src/plugins/frontmatter.ts index 420db77ec..ec9ebf42f 100644 --- a/packages/comark/src/plugins/frontmatter.ts +++ b/packages/comark/src/plugins/frontmatter.ts @@ -19,11 +19,15 @@ */ import { defineComarkPlugin } from '../utils/helpers.ts' -import { parseFrontmatter } from '../internal/frontmatter.ts' + +// The YAML parser loads only for documents that start with frontmatter. +const loadFrontmatter = () => import('../internal/parse/frontmatter.ts') export default defineComarkPlugin(() => ({ name: 'frontmatter', - pre(state) { + async pre(state) { + if (!state.markdown.startsWith('---')) return + const { parseFrontmatter } = await loadFrontmatter() const { content, data, frontmatterText } = parseFrontmatter(state.markdown) state.markdown = content state.frontmatter = data diff --git a/packages/comark/src/plugins/json-render.ts b/packages/comark/src/plugins/json-render.ts index cb5faffd3..146c30a87 100644 --- a/packages/comark/src/plugins/json-render.ts +++ b/packages/comark/src/plugins/json-render.ts @@ -2,7 +2,7 @@ import type { Spec, UIElement } from '@json-render/core' import type { ElementNodeAttributes, Node } from 'comark' import { defineComarkPlugin } from 'comark' import { textContent, visit } from 'comark/utils' -import { parseYaml } from '../internal/yaml.ts' +import { parseYaml } from '../internal/parse/yaml.ts' // Budgets for spec expansion. Specs are author-controlled and elements can // reference the same key many times (a DAG), so recursive materialization diff --git a/packages/comark/src/render/index.ts b/packages/comark/src/render/index.ts index 189caaa99..86fd27b81 100644 --- a/packages/comark/src/render/index.ts +++ b/packages/comark/src/render/index.ts @@ -1,5 +1,4 @@ import type { MarkdownDocument, RendererOptions, RenderMarkdownOptions } from 'comark' -import { renderFrontmatter } from '../internal/frontmatter.ts' import { createState, one } from '../internal/stringify/state.ts' import { handlers } from '../internal/stringify/handlers/index.ts' @@ -16,9 +15,6 @@ export type { NodeTransformResult, } from '../types.ts' -// Re-export frontmatter renderer -export { renderFrontmatter } from '../internal/frontmatter.ts' - // Re-export attribute resolvers for custom handlers that want to honor `:prefix` bindings export { resolveAttributes, resolveAttribute } from '../internal/stringify/attributes.ts' @@ -53,5 +49,9 @@ export async function renderMarkdown( options?: RenderMarkdownOptions ): Promise { const content = await render(document, { format: 'markdown/comark', ...options }) - return renderFrontmatter((document as MarkdownDocument).frontmatter || {}, content, options?.frontmatterOptions) + const frontmatter = (document as MarkdownDocument).frontmatter + if (!frontmatter || Object.keys(frontmatter).length === 0) return content.trim() + // The YAML serializer loads only for documents that have frontmatter. + const { renderFrontmatter } = await import('../internal/stringify/frontmatter.ts') + return renderFrontmatter(frontmatter, content, options?.frontmatterOptions) } diff --git a/packages/comark/test/frontmatter.test.ts b/packages/comark/test/frontmatter.test.ts index 305b80bc8..b43a2862f 100644 --- a/packages/comark/test/frontmatter.test.ts +++ b/packages/comark/test/frontmatter.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest' -import { parseFrontmatter, renderFrontmatter } from '../src/internal/frontmatter' +import { parseFrontmatter, renderFrontmatter } from 'comark/frontmatter' import { createMarkdownParser, parseMarkdown } from '../src/index' describe('parseFrontmatter', () => { diff --git a/packages/comark/test/index.test.ts b/packages/comark/test/index.test.ts index 068328d2d..d59c5acf6 100644 --- a/packages/comark/test/index.test.ts +++ b/packages/comark/test/index.test.ts @@ -1,7 +1,7 @@ import { describe, it, expect, beforeAll } from 'vitest' import { readdirSync, readFileSync } from 'node:fs' import { join } from 'node:path' -import { parseFrontmatter } from '../src/internal/frontmatter' +import { parseFrontmatter } from 'comark/frontmatter' import { parseMarkdown } from 'comark' import { renderMarkdown } from 'comark/render' import shiki from 'comark/plugins/shiki' diff --git a/packages/comark/test/yaml-lazy-load.test.ts b/packages/comark/test/yaml-lazy-load.test.ts new file mode 100644 index 000000000..91ce30985 --- /dev/null +++ b/packages/comark/test/yaml-lazy-load.test.ts @@ -0,0 +1,60 @@ +import { execFileSync } from 'node:child_process' +import { expect, it } from 'vitest' + +// Runs `script` in a fresh Node process that records every js-yaml module it loads. +function yamlLoads(script: string): string { + return execFileSync( + process.execPath, + [ + '--input-type=module', + '-e', + ` + import { registerHooks } from 'node:module' + import assert from 'node:assert/strict' + let yamlLoaded = false + registerHooks({ + load(url, context, next) { + if (url.includes('js-yaml')) yamlLoaded = true + return next(url, context) + } + }) + ${script} + process.stdout.write(yamlLoaded ? 'loaded' : 'not loaded') + `, + ], + { cwd: process.cwd(), encoding: 'utf8' } + ) +} + +it('parses and renders a document without frontmatter or YAML attributes without loading YAML', () => { + const result = yamlLoads(` + const { createMarkdownParser } = await import('comark/core') + const { default: frontmatter } = await import('comark/plugins/frontmatter') + const { renderMarkdown } = await import('comark/render') + const tree = await createMarkdownParser({ plugins: [frontmatter()] })('# Hello\\n\\nSome *text*') + assert.deepEqual(tree.frontmatter, {}) + assert.equal(await renderMarkdown(tree), '# Hello\\n\\nSome *text*') + `) + expect(result).toBe('not loaded') +}) + +it('loads YAML for frontmatter and YAML attributes', () => { + const result = yamlLoads(` + const { createMarkdownParser } = await import('comark/core') + const { default: frontmatter } = await import('comark/plugins/frontmatter') + const { renderMarkdown } = await import('comark/render') + const tree = await createMarkdownParser({ plugins: [frontmatter()] })('---\\ntitle: Hi\\n---\\n\\n# Hello') + assert.deepEqual(tree.frontmatter, { title: 'Hi' }) + assert.equal(await renderMarkdown(tree), '---\\ntitle: Hi\\n---\\n\\n# Hello') + const card = { nodes: [['card', { title: 'Card' }, 'Body']] } + assert.equal(await renderMarkdown(card, { maxInlineAttributes: 0 }), '::card\\n\`\`\`yaml [props]\\ntitle: Card\\n\`\`\`\\nBody\\n::') + `) + expect(result).toBe('loaded') +}) + +it('exports parseFrontmatter and renderFrontmatter from comark/frontmatter only', async () => { + const entry = await import('comark/frontmatter') + expect(Object.keys(entry).sort()).toEqual(['parseFrontmatter', 'renderFrontmatter']) + expect('parseFrontmatter' in (await import('comark'))).toBe(false) + expect('renderFrontmatter' in (await import('comark/render'))).toBe(false) +}) diff --git a/packages/comark/test/yaml.test.ts b/packages/comark/test/yaml.test.ts index 7208cf53e..d9c6b6614 100644 --- a/packages/comark/test/yaml.test.ts +++ b/packages/comark/test/yaml.test.ts @@ -1,5 +1,5 @@ import { describe, expect, it } from 'vitest' -import { parseYaml } from '../src/internal/yaml' +import { parseYaml } from '../src/internal/parse/yaml' describe('parseYaml', () => { describe('empty documents resolve to undefined', () => { From 88788b2e0aae2355576fb0956222edcde47ec371 Mon Sep 17 00:00:00 2001 From: onmax Date: Fri, 6 Nov 2026 13:23:41 +0100 Subject: [PATCH 2/5] perf(components)!: defer YAML until props need it Prepare component dependencies after all pre hooks and preload YAML for custom markdown-it rules that can transform source during tokenization. Keep plain default parses free of the YAML parser. Move the synchronous adapter to its own entry and migrate workspace callers. Patch comark-content's frontmatter imports so docs lint can load. Cover component containers, typed props, source transforms and streaming with fresh-process load checks against the built package. BREAKING CHANGE: import markdownItComponents from comark/plugins/components/markdown-it instead of comark/plugins/components. --- AGENTS.md | 7 +- benchmarks/comark-parse.ts | 2 +- benchmarks/comark-render.ts | 2 +- benchmarks/plugin-highlight.ts | 2 +- benchmarks/plugin-punctuation.ts | 2 +- .../11.compare/7.comark-vs-markdown-it.md | 2 +- .../4.plugins/0.defaults/attributes.md | 2 +- .../4.plugins/0.defaults/components.md | 4 +- .../4.plugins/2.custom/1.plugin-api.md | 10 +- .../vitepress/.vitepress/config.ts | 2 +- examples/1.frameworks/vitepress/demo.md | 2 +- packages/comark/src/core.ts | 7 +- packages/comark/src/frontmatter.ts | 2 +- .../comark/src/internal/parse/components.ts | 544 ++++++++++++++++++ .../src/internal/parse/source-stable.ts | 13 + .../src/internal/stringify/attributes.ts | 2 +- packages/comark/src/plugins/attributes.ts | 3 +- packages/comark/src/plugins/components.ts | 527 +---------------- .../src/plugins/components/markdown-it.ts | 5 + packages/comark/src/plugins/frontmatter.ts | 10 +- packages/comark/src/plugins/html.ts | 3 +- packages/comark/src/plugins/linkify.ts | 3 +- packages/comark/src/plugins/task-list.ts | 3 +- packages/comark/src/types.ts | 2 + packages/comark/test/yaml-lazy-load.test.ts | 135 ++++- patches/comark-content@0.4.3.patch | 21 + pnpm-lock.yaml | 5 +- pnpm-workspace.yaml | 1 + test/bundle.test.ts | 16 +- 29 files changed, 796 insertions(+), 543 deletions(-) create mode 100644 packages/comark/src/internal/parse/components.ts create mode 100644 packages/comark/src/internal/parse/source-stable.ts create mode 100644 packages/comark/src/plugins/components/markdown-it.ts create mode 100644 patches/comark-content@0.4.3.patch diff --git a/AGENTS.md b/AGENTS.md index 83464312b..8243a6460 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -68,7 +68,7 @@ packages/comark/ │ │ ├── alert.ts # Alert/callout blocks │ │ ├── frontmatter.ts # YAML frontmatter extraction (default via registerDefaultPlugins) │ │ ├── html.ts # HTML block/inline parsing (default via registerDefaultPlugins) -│ │ ├── components.ts # Block/inline components + spans (`::name`, `:name`, `[text]`) +│ │ ├── components.ts # prepare() loads YAML after all pre hooks; loader for block/inline components + spans (`::name`, `:name`, `[text]`) │ │ ├── attributes.ts # Inline attributes (`{props}` after tokens) │ │ ├── binding.ts # Inline interpolation + shared conditional rendering rules │ │ ├── breaks.ts # Hard line breaks (`
`) from newlines @@ -103,6 +103,7 @@ packages/comark/ │ ├── sanitize.ts # Component props validation and frontmatter sanitization │ ├── parse/ # Parsing pipeline │ │ ├── token-processor.ts # markdown-exit tokens → document nodes +│ │ ├── components.ts # Shared component rules and YAML detection; the synchronous adapter lives in plugins/components/markdown-it.ts │ │ ├── frontmatter.ts # parseFrontmatter() │ │ ├── yaml.ts # parseYaml() │ │ ├── auto-close/ # Self-healing for incomplete markdown @@ -550,7 +551,7 @@ import binding, { Binding, resolveIfWrapper, selectIfBranch, shouldRenderIf } fr import type { IfComparisonOperator, IfProps, IfWrapperTag } from 'comark/plugins/binding' // markdown-it / markdown-exit adapters (e.g. VitePress) -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' // NOTE: All framework packages re-export every core plugin via their own subpath. @@ -598,6 +599,8 @@ import mermaid, { Mermaid } from '@comark/angular/plugins/mermaid' import binding, { Binding, If } from '@comark/angular/plugins/binding' ``` +Plugin `pre` hooks transform markdown in order. Async `prepare(state)` hooks run after all `pre` hooks and before tokenization, so syntax dependencies load for the final source and parser configuration. The components plugin uses `prepare` for YAML props, and preloads YAML for unrecognized markdown-it plugin functions that may generate props. Default rule functions are registered as source-stable in `internal/parse/source-stable.ts`; its synchronous markdown-it adapter lives at `comark/plugins/components/markdown-it` and imports YAML eagerly. + ## Coding Principles ### Performance First diff --git a/benchmarks/comark-parse.ts b/benchmarks/comark-parse.ts index e28b93381..fae31e385 100644 --- a/benchmarks/comark-parse.ts +++ b/benchmarks/comark-parse.ts @@ -1,7 +1,7 @@ import { bench, run, barplot, group } from 'mitata' import MarkdownIt from 'markdown-it' import MarkdownExit from 'markdown-exit' -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' import { createMarkdownParser } from 'comark' diff --git a/benchmarks/comark-render.ts b/benchmarks/comark-render.ts index 8c4901517..3ec27480e 100644 --- a/benchmarks/comark-render.ts +++ b/benchmarks/comark-render.ts @@ -1,7 +1,7 @@ import { bench, run, barplot, group } from 'mitata' import MarkdownIt from 'markdown-it' import MarkdownExit from 'markdown-exit' -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' import { createMarkdownParser } from 'comark' import { renderHtmlFromDocument } from '../packages/comark-html/src/index.ts' diff --git a/benchmarks/plugin-highlight.ts b/benchmarks/plugin-highlight.ts index 4abbaf081..fb0040d63 100644 --- a/benchmarks/plugin-highlight.ts +++ b/benchmarks/plugin-highlight.ts @@ -1,7 +1,7 @@ import { bench, run, group, barplot } from 'mitata' import MarkdownIt from 'markdown-it' import MarkdownExit from 'markdown-exit' -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' import { createMarkdownParser } from 'comark' import shiki, { getHighlighter } from '../packages/comark/src/plugins/shiki' diff --git a/benchmarks/plugin-punctuation.ts b/benchmarks/plugin-punctuation.ts index c7a013b31..74e6ea583 100644 --- a/benchmarks/plugin-punctuation.ts +++ b/benchmarks/plugin-punctuation.ts @@ -1,6 +1,6 @@ import { bench, run, group, barplot } from 'mitata' import MarkdownExit from 'markdown-exit' -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' import { createMarkdownParser } from 'comark' import { printAnsi } from '@comark/ansi' diff --git a/docs/content/11.compare/7.comark-vs-markdown-it.md b/docs/content/11.compare/7.comark-vs-markdown-it.md index 5a8264ad2..a9c6dc094 100644 --- a/docs/content/11.compare/7.comark-vs-markdown-it.md +++ b/docs/content/11.compare/7.comark-vs-markdown-it.md @@ -84,7 +84,7 @@ Plugins that add inline rules, block rules, or core rules work, such as subscrip The reverse also works. If a tool already owns a markdown-it instance, such as VitePress, you can add Comark component and attribute syntax to it: ```ts -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' md.use(markdownItComponents) diff --git a/docs/content/4.plugins/0.defaults/attributes.md b/docs/content/4.plugins/0.defaults/attributes.md index 9409d4731..a9c44395d 100644 --- a/docs/content/4.plugins/0.defaults/attributes.md +++ b/docs/content/4.plugins/0.defaults/attributes.md @@ -109,7 +109,7 @@ md.use(markdownItAttributes) Pair with [components](/plugins/defaults/components) when you also need `::name` / `:name` syntax: ```typescript -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' md.use(markdownItComponents) diff --git a/docs/content/4.plugins/0.defaults/components.md b/docs/content/4.plugins/0.defaults/components.md index 8217f57b8..4368f215a 100644 --- a/docs/content/4.plugins/0.defaults/components.md +++ b/docs/content/4.plugins/0.defaults/components.md @@ -103,8 +103,10 @@ When the components plugin is not active, `autoClose` also skips component-fence For hosts that use markdown-it or markdown-exit directly (for example VitePress), use the exported adapter: +With Comark's default rules, YAML loads only when the source may contain component props. Additional markdown-it plugins can generate props during synchronous tokenization, so an unrecognized markdown-it plugin makes YAML load before parsing. The synchronous markdown-it adapter imports YAML eagerly and has its own entry, `comark/plugins/components/markdown-it`. Move named adapter imports from `comark/plugins/components` to this path. + ```typescript -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' md.use(markdownItComponents) diff --git a/docs/content/4.plugins/2.custom/1.plugin-api.md b/docs/content/4.plugins/2.custom/1.plugin-api.md index ad794a2be..d84a000e8 100644 --- a/docs/content/4.plugins/2.custom/1.plugin-api.md +++ b/docs/content/4.plugins/2.custom/1.plugin-api.md @@ -143,7 +143,7 @@ defineComarkPlugin(() => ({ ## Lifecycle -Plugins hook into two phases of the parsing pipeline: +Plugins can transform the source, prepare parser dependencies, and transform the resulting document: ``` Markdown string @@ -154,6 +154,9 @@ Markdown string └──────────┘ │ ▼ + prepare(state) ← Load dependencies for the final source + │ + ▼ Parse & Build MarkdownDocument │ ▼ @@ -187,6 +190,10 @@ export default defineComarkPlugin(() => ({ | `markdown` | `string` | The raw markdown; modify to change parser input | | `options` | [`ParserOptions`](/reference/parse#options) | The parser configuration | +### `prepare(state)`{lang="ts"} + +Called after every `pre` hook finishes, immediately before tokenization. It receives a read-only `ComarkParsePreState` with the final markdown and parser options, and can return a promise. Use it to load dependencies required by synchronous parser rules. For example, the components plugin loads YAML here when the final source may contain YAML props, including props introduced by a `pre` transform. + ### `post(state)`{lang="ts"} Called after the AST is built. Use it to traverse nodes or populate `meta` with extracted data. @@ -230,6 +237,7 @@ To traverse and transform `tree` nodes, see the AST API page for the `visit()` u | `name` | `string` | A unique identifier for the plugin | | `markdownItPlugins` | [`MarkdownItPlugin[]`](https://markdown-it.github.io/markdown-it/#MarkdownIt) | markdown-it plugins to register on the parser, see [Markdown-it Plugins](/plugins/custom/markdown-it) | | `pre` | `(state: ComarkParsePreState) => Promise \| void` | Hook called before parsing | +| `prepare` | `(state: Readonly) => Promise \| void` | Load dependencies after all source transforms and before tokenization | | `post` | `(state: ComarkParsePostState) => Promise \| void` | Hook called after the AST is built. `state.tree.meta` / `state.tree.frontmatter` are typed as the declared contribution, see [Typed contributions](#typed-contributions). | | `autoClose` | `{ bracketMath?: boolean }` | Auto-close flags for syntax this plugin adds. Flags from all plugins are merged and applied when the parser's `autoClose` is `true`; a custom `autoClose` function ignores them | diff --git a/examples/1.frameworks/vitepress/.vitepress/config.ts b/examples/1.frameworks/vitepress/.vitepress/config.ts index 9f4ec9338..aa0355410 100644 --- a/examples/1.frameworks/vitepress/.vitepress/config.ts +++ b/examples/1.frameworks/vitepress/.vitepress/config.ts @@ -1,5 +1,5 @@ import { defineConfig } from 'vitepress' -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' export default defineConfig({ diff --git a/examples/1.frameworks/vitepress/demo.md b/examples/1.frameworks/vitepress/demo.md index a3687935b..2a1550bb3 100644 --- a/examples/1.frameworks/vitepress/demo.md +++ b/examples/1.frameworks/vitepress/demo.md @@ -30,7 +30,7 @@ This is a danger alert — useful for critical warnings. ```ts // .vitepress/config.ts -import { markdownItComponents } from 'comark/plugins/components' +import { markdownItComponents } from 'comark/plugins/components/markdown-it' import { markdownItAttributes } from 'comark/plugins/attributes' export default defineConfig({ diff --git a/packages/comark/src/core.ts b/packages/comark/src/core.ts index e7cdc772f..ee1713be9 100644 --- a/packages/comark/src/core.ts +++ b/packages/comark/src/core.ts @@ -90,7 +90,7 @@ export function createMarkdownParser { const state = { options, @@ -135,6 +135,11 @@ export function createMarkdownParser plugin.pre!(state)) } + for (const plugin of plugins) { + if (!plugin.prepare) continue + await withSpan(tracer, `comark:prepare:${plugin.name}`, () => plugin.prepare!(state)) + } + try { state.tokens = withSpan(tracer, 'comark:tokenize', () => md.parse(state.markdown, {})) } catch (e) { diff --git a/packages/comark/src/frontmatter.ts b/packages/comark/src/frontmatter.ts index b3c167dc8..8e115a1cb 100644 --- a/packages/comark/src/frontmatter.ts +++ b/packages/comark/src/frontmatter.ts @@ -6,7 +6,7 @@ * import { parseFrontmatter, renderFrontmatter } from 'comark/frontmatter' * * const { content, data } = parseFrontmatter('---\ntitle: Hi\n---\n\n# Hello') - * // data → { title: 'Hi' }, content → '\n# Hello' + * // data → { title: 'Hi' }, content → '\n\n# Hello' * * renderFrontmatter({ title: 'Hi' }, '# Hello') * // → '---\ntitle: Hi\n---\n\n# Hello' diff --git a/packages/comark/src/internal/parse/components.ts b/packages/comark/src/internal/parse/components.ts new file mode 100644 index 000000000..7731768e1 --- /dev/null +++ b/packages/comark/src/internal/parse/components.ts @@ -0,0 +1,544 @@ +import type { PluginSimple, Token } from 'markdown-exit/core' +import { findClosingBracket, parseBracketContent } from './syntax/brackets.ts' +import { parseBlockParams } from './syntax/block-params.ts' +import { tokenizeDedented } from './indent.ts' + +/** + * A component name must start with a letter or `$`, followed by word chars, + * `$` or `-`. Mirrors the block name grammar (`RE_BLOCK_NAME = /^[a-z$]/i`). + */ +const RE_COMPONENT_NAME = /^[a-z$][\w$-]*/i + +/** + * Whether `name` begins with a syntactically valid component name. + * + * This prevents sequences such as `:8100` or `::30` from being treated as + * components — a purely numeric name is not a valid component and would + * otherwise produce invalid output like `createElement('8100')` (inline) or + * throw `Invalid block params` (block). + */ +function isValidComponentName(name: string): boolean { + return RE_COMPONENT_NAME.test(name) +} + +const blockYamlLines: Record = { + '---': '---', + '```yaml [props]': '```', + '~~~yaml [props]': '~~~', + '```yml [props]': '```', + '~~~yml [props]': '~~~', +} + +const markdownItComarkBlock = ( + md: Parameters[0], + parseYaml: typeof import('./yaml.ts').parseYaml +): void => { + const min_markers = 2 + const marker_str = ':' + const marker_char = marker_str.charCodeAt(0) + + md.block.ruler.before( + 'fence', + 'comark_block_shorthand', + function comark_block_shorthand(state, startLine, _endLine, silent) { + const line = state.src.slice(state.bMarks[startLine] + state.tShift[startLine], state.eMarks[startLine]) + + if (line[0] !== ':' || !isValidComponentName(line.slice(1))) return false + + const { name, content, props, remaining } = parseBlockParams(line.slice(1)) + + // If there's unparsed remaining content, treat it as inline component in a paragraph + if (remaining) return false + + if (!silent) { + if (content !== undefined) { + const tokenOpen = state.push('mdc_block_shorthand_open', name, 1) + props?.forEach(([key, value]) => { + if (key === 'class') tokenOpen.attrJoin(key, value) + else tokenOpen.attrSet(key, value) + }) + tokenOpen.map = [startLine, startLine + 1] + + const inline = state.push('inline', '', 0) + inline.content = content + inline.children = [] + + const tokenClose = state.push('mdc_block_shorthand_close', name, -1) + tokenClose.map = [startLine, startLine + 1] + } else { + const token = state.push('mdc_block_shorthand', name, 0) + token.map = [startLine, startLine + 1] + props?.forEach(([key, value]) => { + if (key === 'class') token.attrJoin(key, value) + else token.attrSet(key, value) + }) + } + } + + state.line = startLine + 1 + return true + } + ) + + md.block.ruler.before( + 'fence', + 'comark_block', + function comark_block(state, startLine, endLine, silent) { + let pos: number + let nextLine: number + let auto_closed = false + let start = state.bMarks[startLine] + state.tShift[startLine] + let max = state.eMarks[startLine] + const indent = state.sCount[startLine] + + // Track code fences (``` or ~~~) so we don't match closing :: inside them + let inCodeFence = false + let codeFenceCharCode = 0 + let codeFenceCount = 0 + + // Track nesting depth for blocks with the same marker count + let nestingDepth = 0 + + if (state.src[start] !== ':') return false + + for (pos = start + 1; pos <= max; pos++) { + if (marker_str !== state.src[pos]) break + } + + const marker_count = Math.floor(pos - start) + if (marker_count < min_markers) return false + + const markup = state.src.slice(start, pos) + + // Bail out (plain text) on an invalid name instead of letting + // parseBlockParams throw on e.g. `::8100`. + const nameStart = state.skipSpaces(pos) + if (nameStart < max && !isValidComponentName(state.src.slice(nameStart, max))) return false + + const params = parseBlockParams(state.src.slice(pos, max)) + + if (!params.name) return false + + if (silent) return true + + // Columns to strip from each child line, indexed from `startLine + 1`. + const childShifts: number[] = [] + let codeFenceShift = 0 + let hasOutdentedChild = false + + nextLine = startLine + + for (;;) { + nextLine++ + if (nextLine >= endLine) break + + start = state.bMarks[nextLine] + state.tShift[nextLine] + max = state.eMarks[nextLine] + + if (start < max && state.sCount[nextLine] < state.blkIndent) break + + const lineIndent = start >= max ? indent : state.sCount[nextLine] + if (lineIndent < indent) hasOutdentedChild = true + childShifts.push(start >= max ? 0 : inCodeFence ? codeFenceShift : Math.min(indent, lineIndent)) + + const lineCharCode = state.src.charCodeAt(start) + + // Detect closing code fence (``` or ~~~) + if (inCodeFence) { + if (lineCharCode === codeFenceCharCode) { + let fencePos = start + 1 + while (fencePos < max && state.src.charCodeAt(fencePos) === codeFenceCharCode) fencePos++ + if (fencePos - start >= codeFenceCount) { + const afterFence = state.skipSpaces(fencePos) + if (afterFence >= max) inCodeFence = false + } + } + continue + } + + // Detect opening code fence (``` or ~~~) + if (lineCharCode === 0x60 /* ` */ || lineCharCode === 0x7e /* ~ */) { + let fencePos = start + 1 + while (fencePos < max && state.src.charCodeAt(fencePos) === lineCharCode) fencePos++ + if (fencePos - start >= 3) { + inCodeFence = true + codeFenceCharCode = lineCharCode + codeFenceCount = fencePos - start + codeFenceShift = childShifts[childShifts.length - 1] + continue + } + } + + if (marker_char !== lineCharCode) continue + + for (pos = start + 1; pos <= max; pos++) { + if (marker_str !== state.src[pos]) break + } + + // Closing fence must match the opening fence length + if (pos - start !== marker_count) continue + + pos = state.skipSpaces(pos) + + if (pos < max) { + // A new nested block opens with same marker count + nestingDepth++ + continue + } + + if (nestingDepth > 0) { + nestingDepth-- + continue + } + + auto_closed = true + break + } + + const old_parent = state.parentType + const old_line_max = state.lineMax + state.parentType = 'comark_block' + + // Prevent lazy continuations from going past our end marker + state.lineMax = nextLine + + const tokenOpen = state.push('mdc_block_open', params.name, 1) + tokenOpen.markup = markup + tokenOpen.block = true + tokenOpen.info = params.name + tokenOpen.map = [startLine, nextLine] + + params.props?.forEach(([key, value]) => { + if (key === 'class') tokenOpen.attrJoin(key, value) + else tokenOpen.attrSet(key, value) + }) + + // Render bracket content as the first paragraph: `::block[Content]\n::` + if (params.content !== undefined) { + const pOpen = state.push('paragraph_open', 'p', 1) + pOpen.map = [startLine, startLine + 1] + const inline = state.push('inline', '', 0) + inline.content = params.content + inline.children = [] + state.push('paragraph_close', 'p', -1) + } + + state.env.comarkBlockTokens ||= [] as Token[] + state.env.comarkBlockTokens.unshift(tokenOpen) + + if (!hasOutdentedChild || !tokenizeDedented(state, startLine + 1, nextLine, childShifts)) { + const blkIndent = state.blkIndent + state.blkIndent = indent + state.md.block.tokenize(state, startLine + 1, nextLine) + state.blkIndent = blkIndent + } + + state.env.comarkBlockTokens.shift() + + const tokenClose = state.push('mdc_block_close', params.name, -1) + tokenClose.map = [startLine, nextLine] + tokenClose.markup = state.src.slice(start, pos) + tokenClose.block = true + + // Hide the wrapper paragraph for single-paragraph blocks + state.tokens + .slice(state.tokens.indexOf(tokenOpen) + 1, state.tokens.indexOf(tokenClose)) + .filter((i) => i.level === tokenOpen.level + 1) + .forEach((i, _, arr) => { + if (arr.length <= 2 && i.tag === 'p') i.hidden = true + }) + + state.parentType = old_parent + state.lineMax = old_line_max + state.line = nextLine + (auto_closed ? 1 : 0) + + return true + }, + { + alt: ['paragraph', 'reference', 'blockquote', 'list'], + } + ) + + md.block.ruler.after('code', 'comark_block_yaml', function comark_block_yaml(state, startLine, endLine, silent) { + if (!state.env.comarkBlockTokens?.length) return false + + const start = state.bMarks[startLine] + state.tShift[startLine] + const end = state.eMarks[startLine] + + const line = state.src.slice(start, end) + const blockAttributesClosingFence = blockYamlLines[line] || '' + + if (!blockAttributesClosingFence) return false + + // The `---` fence is only valid on the line immediately after the component opener. Any other `---` is a thematic break. + if (line === '---') { + const parentOpenLine = state.env.comarkBlockTokens[0].map?.[0] + if (parentOpenLine === undefined || startLine !== parentOpenLine + 1) return false + } + + let lineEnd = startLine + 1 + let found = false + while (lineEnd < endLine) { + const inner = state.src.slice(state.bMarks[lineEnd] + state.tShift[startLine], state.eMarks[lineEnd]) + if (inner === blockAttributesClosingFence) { + found = true + break + } + lineEnd += 1 + } + + if (!found) return false + + if (!silent) { + const yaml = state.getLines(startLine + 1, lineEnd, state.blkIndent, false) + const data = parseYaml(yaml) + const token = state.env.comarkBlockTokens[0] + Object.entries(data || {}).forEach(([key, value]) => { + if (key === 'class') { + token.attrJoin(key, value as string) + return + } + // Match @nuxtjs/mdc: non-string YAML values are stored as `:`-prefixed + // bindings with a JSON-string payload. Framework renderers (and + // resolveAttributes with parseJson) restore native types; quoted YAML + // strings stay unprefixed and remain strings (#364). + if (typeof value === 'string') { + token.attrSet(key, value) + } else { + token.attrSet(`:${key}`, JSON.stringify(value)) + } + }) + } + + state.line = lineEnd + 1 + return true + }) + + md.block.ruler.after( + 'code', + 'comark_block_slots', + function comark_block_slots(state, startLine, endLine, silent) { + if (!state.env.comarkBlockTokens?.length) return false + + const start = state.bMarks[startLine] + state.tShift[startLine] + + if (!(state.src[start] === '#' && state.src[start + 1] !== ' ' && state.src[start + 1] !== '#')) return false + + const line = state.src.slice(start, state.eMarks[startLine]) + + const slotParams = line.slice(1) + if (!isValidComponentName(slotParams.trimStart())) return false + const { name, props, remaining } = parseBlockParams(slotParams) + if (remaining) return false + + if (silent) return true + + let lineEnd = startLine + 1 + let inCodeFence = false + let codeFenceChar = '' + let codeFenceCount = 0 + while (lineEnd < endLine) { + const inner = state.src.slice(state.bMarks[lineEnd] + state.tShift[startLine], state.eMarks[lineEnd]) + + if (inCodeFence) { + // Look for matching closing fence (same char, >= opening count, nothing but spaces after) + if (inner[0] === codeFenceChar) { + let fencePos = 1 + while (fencePos < inner.length && inner[fencePos] === codeFenceChar) fencePos++ + if (fencePos >= codeFenceCount && inner.slice(fencePos).trim() === '') { + inCodeFence = false + } + } + lineEnd += 1 + continue + } + + // Detect opening code fence (``` or ~~~, length >= 3) + if (inner[0] === '`' || inner[0] === '~') { + const ch = inner[0] + let fencePos = 1 + while (fencePos < inner.length && inner[fencePos] === ch) fencePos++ + if (fencePos >= 3) { + inCodeFence = true + codeFenceChar = ch + codeFenceCount = fencePos + lineEnd += 1 + continue + } + } + + if (/^#\w+/.test(inner) || inner.startsWith('::')) break + lineEnd += 1 + } + + // Restore lineMax after tokenizing so it doesn't leak a narrower bound to + // whatever comes after this slot (see `comark_block`'s save/restore above). + const oldLineMax = state.lineMax + const slot = state.push('mdc_block_slot_open', 'template', 1) + slot.attrSet('name', `${name}`) + props?.forEach(([key, value]) => { + if (key === 'class') slot.attrJoin(key, value) + else slot.attrSet(key, value) + }) + + state.line = startLine + 1 + state.lineMax = lineEnd + + state.md.block.tokenize(state, startLine + 1, lineEnd) + + state.push('mdc_block_slot_close', 'template', -1) + + state.line = lineEnd + state.lineMax = oldLineMax + + return true + }, + { alt: ['paragraph'] } + ) +} + +const ALLOWED_PREV_CHARS = new Set([' ', '\t', '\n', '*', '_', '[', ']', '}', ')', '>']) + +const markdownItInlineComponent: PluginSimple = (md) => { + md.inline.ruler.after('entity', 'comark_inline_component', (state, silent) => { + const start = state.pos + if (state.src[start] !== ':') return false + + const prevChar = state.src[start - 1] + if (start > 0 && !ALLOWED_PREV_CHARS.has(prevChar)) return false + + let index = start + 1 + let nameEnd = -1 + let contentStart = -1 + let contentEnd = -1 + + while (index < state.src.length) { + const char = state.src[index] + if (char === '[') { + nameEnd = index + const result = parseBracketContent(state.src, index) + if (result) { + contentStart = index + 1 + contentEnd = result.endIndex - 1 + index = result.endIndex + } + break + } + if (!/[\w$-]/.test(char)) break + index += 1 + } + + if (nameEnd === -1) nameEnd = index + + // Empty name + if (nameEnd <= start + 1) return false + + const name = state.src.slice(start + 1, nameEnd) + if (!isValidComponentName(name)) return false + + state.pos = index + + if (silent) return true + + if (contentStart !== -1) { + state.push('mdc_inline_component_open', name, 1) + + const oldPos = state.pos + const oldPosMax = state.posMax + state.pos = contentStart + state.posMax = contentEnd + state.md.inline.tokenize(state) + state.pos = oldPos + state.posMax = oldPosMax + + state.push('mdc_inline_component_close', name, -1) + } else { + state.push('mdc_inline_component', name, 0) + } + + return true + }) +} + +// #region Inline span (`[text]` / `[text]{attrs}`) + +const markdownItInlineSpan: PluginSimple = (md) => { + md.inline.ruler.before('link', 'comark_inline_span', (state, silent) => { + const start = state.pos + if (state.src[start] !== '[') return false + + // An unclosed span consumes to the end of input (streaming auto-close) + const close = findClosingBracket(state.src, start) + const index = close === -1 ? state.src.length : close + + // Don't match `[text](url)` or `[text][ref]` — let the link parser handle those + const nextChar = state.src[index + 1] + if (nextChar === '(' || nextChar === '[') return false + + // Inside a link label, bare `[text]` stays literal (plain-markdown behavior, + // e.g. `[[1] Document](#)`); only an explicit `[text]{attrs}` span matches + if (state.linkLevel > 0 && nextChar !== '{') return false + + // Returning `false` lets `parseLinkLabel`'s own depth tracking consume nested brackets and the outer link parse + if (silent) return false + + state.push('mdc_inline_span_open', 'span', 1) + + const oldPos = state.pos + const oldPosMax = state.posMax + state.pos = start + 1 + state.posMax = index + state.md.inline.tokenize(state) + state.pos = oldPos + state.posMax = oldPosMax + + state.push('mdc_inline_span_close', 'span', -1) + + state.pos = index + 1 + + return true + }) +} + +// #endregion + +export function createMarkdownItComponents(parseYaml: typeof import('./yaml.ts').parseYaml): PluginSimple { + return (md) => { + markdownItComarkBlock(md, parseYaml) + md.use(markdownItInlineSpan) + md.use(markdownItInlineComponent) + } +} + +const blockYamlFences = Object.keys(blockYamlLines) + +// Container prefixes and indentation are stripped during tokenization. Matching +// line suffixes here also covers YAML props inside lists and blockquotes. +export function hasYamlProps(source: string): boolean { + if (!source.includes('::')) return false + let previousComponent = false + for (let start = 0; start < source.length;) { + let end = start + while (end < source.length && source[end] !== '\n' && source[end] !== '\r') end++ + + for (const fence of blockYamlFences) { + if (fence === '---' && !previousComponent) continue + if (end - start >= fence.length && source.endsWith(fence, end)) return true + } + + previousComponent = false + for (let pos = start; pos < end; pos++) { + if (source[pos] !== ':' || source[pos + 1] !== ':') continue + while (pos < end && source[pos] === ':') pos++ + while (pos < end && (source[pos] === ' ' || source[pos] === '\t')) pos++ + const code = source.charCodeAt(pos) | 32 + if (pos < end && ((code >= 97 && code <= 122) || source[pos] === '$')) { + previousComponent = true + break + } + } + + start = end + (source[end] === '\r' && source[end + 1] === '\n' ? 2 : 1) + } + return false +} diff --git a/packages/comark/src/internal/parse/source-stable.ts b/packages/comark/src/internal/parse/source-stable.ts new file mode 100644 index 000000000..10d61671e --- /dev/null +++ b/packages/comark/src/internal/parse/source-stable.ts @@ -0,0 +1,13 @@ +import type { MarkdownExitPlugin, MarkdownItPlugin } from '../../types.ts' + +const sourceStablePlugins = new WeakSet() + +/** Only rules known not to introduce YAML component props can skip eager preparation. */ +export function markSourceStable(plugin: T): T { + sourceStablePlugins.add(plugin) + return plugin +} + +export function isSourceStable(plugin: MarkdownExitPlugin | MarkdownItPlugin): boolean { + return sourceStablePlugins.has(plugin) +} diff --git a/packages/comark/src/internal/stringify/attributes.ts b/packages/comark/src/internal/stringify/attributes.ts index 4b79ad1d0..366022749 100644 --- a/packages/comark/src/internal/stringify/attributes.ts +++ b/packages/comark/src/internal/stringify/attributes.ts @@ -130,7 +130,7 @@ function normalizeValue(value: unknown): unknown { export async function comarkYamlAttributes( attributes: Record, style: 'frontmatter' | 'codeblock' = 'codeblock' -) { +): Promise { // Normalize attribute values for YAML serialization: // - `:`-prefixed JSON literals (`:count="42"`, `:config={…}`) restore to // native values and drop the prefix — matching @nuxtjs/mdc stringify. diff --git a/packages/comark/src/plugins/attributes.ts b/packages/comark/src/plugins/attributes.ts index c783837b6..e2d5554f1 100644 --- a/packages/comark/src/plugins/attributes.ts +++ b/packages/comark/src/plugins/attributes.ts @@ -13,6 +13,7 @@ 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 { markSourceStable } from '../internal/parse/source-stable.ts' import { searchProps } from '../internal/parse/syntax/props.ts' const TEXT_TOKENS = new Set(['text', 'text_special', 'softbreak', 'hardbreak']) @@ -223,5 +224,5 @@ export const markdownItAttributes: PluginSimple = markdownItInlineProps export default defineComarkPlugin(() => ({ name: 'attributes', - markdownItPlugins: [markdownItAttributes as unknown as MarkdownItPlugin], + markdownItPlugins: [markSourceStable(markdownItAttributes as unknown as MarkdownItPlugin)], })) diff --git a/packages/comark/src/plugins/components.ts b/packages/comark/src/plugins/components.ts index 6e9d99e6e..7ba4e0d98 100644 --- a/packages/comark/src/plugins/components.ts +++ b/packages/comark/src/plugins/components.ts @@ -8,518 +8,31 @@ * @see https://comark.dev/syntax/components */ -import type { PluginSimple, Token } from 'markdown-exit/core' -import type { MarkdownItPlugin } from 'comark' +import type { ComarkParsePreState, MarkdownItPlugin } from '../types.ts' import { defineComarkPlugin } from '../utils/helpers.ts' -import { findClosingBracket, parseBracketContent } from '../internal/parse/syntax/brackets.ts' -import { parseBlockParams } from '../internal/parse/syntax/block-params.ts' -import { parseYaml } from '../internal/parse/yaml.ts' -import { tokenizeDedented } from '../internal/parse/indent.ts' +import { markSourceStable, isSourceStable } from '../internal/parse/source-stable.ts' +import { createMarkdownItComponents, hasYamlProps } from '../internal/parse/components.ts' -/** - * A component name must start with a letter or `$`, followed by word chars, - * `$` or `-`. Mirrors the block name grammar (`RE_BLOCK_NAME = /^[a-z$]/i`). - */ -const RE_COMPONENT_NAME = /^[a-z$][\w$-]*/i - -/** - * Whether `name` begins with a syntactically valid component name. - * - * This prevents sequences such as `:8100` or `::30` from being treated as - * components — a purely numeric name is not a valid component and would - * otherwise produce invalid output like `createElement('8100')` (inline) or - * throw `Invalid block params` (block). - */ -function isValidComponentName(name: string): boolean { - return RE_COMPONENT_NAME.test(name) -} - -const blockYamlLines: Record = { - '---': '---', - '```yaml [props]': '```', - '~~~yaml [props]': '~~~', - '```yml [props]': '```', - '~~~yml [props]': '~~~', -} - -const markdownItComarkBlock: PluginSimple = (md) => { - const min_markers = 2 - const marker_str = ':' - const marker_char = marker_str.charCodeAt(0) - - md.block.ruler.before( - 'fence', - 'comark_block_shorthand', - function comark_block_shorthand(state, startLine, _endLine, silent) { - const line = state.src.slice(state.bMarks[startLine] + state.tShift[startLine], state.eMarks[startLine]) - - if (line[0] !== ':' || !isValidComponentName(line.slice(1))) return false - - const { name, content, props, remaining } = parseBlockParams(line.slice(1)) - - // If there's unparsed remaining content, treat it as inline component in a paragraph - if (remaining) return false - - if (!silent) { - if (content !== undefined) { - const tokenOpen = state.push('mdc_block_shorthand_open', name, 1) - props?.forEach(([key, value]) => { - if (key === 'class') tokenOpen.attrJoin(key, value) - else tokenOpen.attrSet(key, value) - }) - tokenOpen.map = [startLine, startLine + 1] - - const inline = state.push('inline', '', 0) - inline.content = content - inline.children = [] - - const tokenClose = state.push('mdc_block_shorthand_close', name, -1) - tokenClose.map = [startLine, startLine + 1] - } else { - const token = state.push('mdc_block_shorthand', name, 0) - token.map = [startLine, startLine + 1] - props?.forEach(([key, value]) => { - if (key === 'class') token.attrJoin(key, value) - else token.attrSet(key, value) - }) - } - } - - state.line = startLine + 1 - return true - } - ) - - md.block.ruler.before( - 'fence', - 'comark_block', - function comark_block(state, startLine, endLine, silent) { - let pos: number - let nextLine: number - let auto_closed = false - let start = state.bMarks[startLine] + state.tShift[startLine] - let max = state.eMarks[startLine] - const indent = state.sCount[startLine] - - // Track code fences (``` or ~~~) so we don't match closing :: inside them - let inCodeFence = false - let codeFenceCharCode = 0 - let codeFenceCount = 0 - - // Track nesting depth for blocks with the same marker count - let nestingDepth = 0 - - if (state.src[start] !== ':') return false - - for (pos = start + 1; pos <= max; pos++) { - if (marker_str !== state.src[pos]) break - } - - const marker_count = Math.floor(pos - start) - if (marker_count < min_markers) return false - - const markup = state.src.slice(start, pos) - - // Bail out (plain text) on an invalid name instead of letting - // parseBlockParams throw on e.g. `::8100`. - const nameStart = state.skipSpaces(pos) - if (nameStart < max && !isValidComponentName(state.src.slice(nameStart, max))) return false - - const params = parseBlockParams(state.src.slice(pos, max)) - - if (!params.name) return false - - if (silent) return true - - // Columns to strip from each child line, indexed from `startLine + 1`. - const childShifts: number[] = [] - let codeFenceShift = 0 - let hasOutdentedChild = false - - nextLine = startLine - - for (;;) { - nextLine++ - if (nextLine >= endLine) break - - start = state.bMarks[nextLine] + state.tShift[nextLine] - max = state.eMarks[nextLine] - - if (start < max && state.sCount[nextLine] < state.blkIndent) break - - const lineIndent = start >= max ? indent : state.sCount[nextLine] - if (lineIndent < indent) hasOutdentedChild = true - childShifts.push(start >= max ? 0 : inCodeFence ? codeFenceShift : Math.min(indent, lineIndent)) - - const lineCharCode = state.src.charCodeAt(start) - - // Detect closing code fence (``` or ~~~) - if (inCodeFence) { - if (lineCharCode === codeFenceCharCode) { - let fencePos = start + 1 - while (fencePos < max && state.src.charCodeAt(fencePos) === codeFenceCharCode) fencePos++ - if (fencePos - start >= codeFenceCount) { - const afterFence = state.skipSpaces(fencePos) - if (afterFence >= max) inCodeFence = false - } - } - continue - } - - // Detect opening code fence (``` or ~~~) - if (lineCharCode === 0x60 /* ` */ || lineCharCode === 0x7e /* ~ */) { - let fencePos = start + 1 - while (fencePos < max && state.src.charCodeAt(fencePos) === lineCharCode) fencePos++ - if (fencePos - start >= 3) { - inCodeFence = true - codeFenceCharCode = lineCharCode - codeFenceCount = fencePos - start - codeFenceShift = childShifts[childShifts.length - 1] - continue - } - } - - if (marker_char !== lineCharCode) continue - - for (pos = start + 1; pos <= max; pos++) { - if (marker_str !== state.src[pos]) break - } - - // Closing fence must match the opening fence length - if (pos - start !== marker_count) continue - - pos = state.skipSpaces(pos) - - if (pos < max) { - // A new nested block opens with same marker count - nestingDepth++ - continue - } - - if (nestingDepth > 0) { - nestingDepth-- - continue - } - - auto_closed = true - break - } - - const old_parent = state.parentType - const old_line_max = state.lineMax - state.parentType = 'comark_block' - - // Prevent lazy continuations from going past our end marker - state.lineMax = nextLine - - const tokenOpen = state.push('mdc_block_open', params.name, 1) - tokenOpen.markup = markup - tokenOpen.block = true - tokenOpen.info = params.name - tokenOpen.map = [startLine, nextLine] - - params.props?.forEach(([key, value]) => { - if (key === 'class') tokenOpen.attrJoin(key, value) - else tokenOpen.attrSet(key, value) - }) - - // Render bracket content as the first paragraph: `::block[Content]\n::` - if (params.content !== undefined) { - const pOpen = state.push('paragraph_open', 'p', 1) - pOpen.map = [startLine, startLine + 1] - const inline = state.push('inline', '', 0) - inline.content = params.content - inline.children = [] - state.push('paragraph_close', 'p', -1) - } - - state.env.comarkBlockTokens ||= [] as Token[] - state.env.comarkBlockTokens.unshift(tokenOpen) - - if (!hasOutdentedChild || !tokenizeDedented(state, startLine + 1, nextLine, childShifts)) { - const blkIndent = state.blkIndent - state.blkIndent = indent - state.md.block.tokenize(state, startLine + 1, nextLine) - state.blkIndent = blkIndent - } - - state.env.comarkBlockTokens.shift() - - const tokenClose = state.push('mdc_block_close', params.name, -1) - tokenClose.map = [startLine, nextLine] - tokenClose.markup = state.src.slice(start, pos) - tokenClose.block = true - - // Hide the wrapper paragraph for single-paragraph blocks - state.tokens - .slice(state.tokens.indexOf(tokenOpen) + 1, state.tokens.indexOf(tokenClose)) - .filter((i) => i.level === tokenOpen.level + 1) - .forEach((i, _, arr) => { - if (arr.length <= 2 && i.tag === 'p') i.hidden = true - }) - - state.parentType = old_parent - state.lineMax = old_line_max - state.line = nextLine + (auto_closed ? 1 : 0) - - return true - }, - { - alt: ['paragraph', 'reference', 'blockquote', 'list'], - } - ) +let yaml: typeof import('../internal/parse/yaml.ts') | undefined - md.block.ruler.after('code', 'comark_block_yaml', function comark_block_yaml(state, startLine, endLine, silent) { - if (!state.env.comarkBlockTokens?.length) return false +const markdownItComponents = createMarkdownItComponents((content) => { + if (!yaml) throw new Error('Component YAML props were not loaded before tokenization') + return yaml.parseYaml(content) +}) - const start = state.bMarks[startLine] + state.tShift[startLine] - const end = state.eMarks[startLine] - - const line = state.src.slice(start, end) - const blockAttributesClosingFence = blockYamlLines[line] || '' - - if (!blockAttributesClosingFence) return false - - // The `---` fence is only valid on the line immediately after the component opener. Any other `---` is a thematic break. - if (line === '---') { - const parentOpenLine = state.env.comarkBlockTokens[0].map?.[0] - if (parentOpenLine === undefined || startLine !== parentOpenLine + 1) return false - } - - let lineEnd = startLine + 1 - let found = false - while (lineEnd < endLine) { - const inner = state.src.slice(state.bMarks[lineEnd] + state.tShift[startLine], state.eMarks[lineEnd]) - if (inner === blockAttributesClosingFence) { - found = true - break - } - lineEnd += 1 - } - - if (!found) return false - - if (!silent) { - const yaml = state.getLines(startLine + 1, lineEnd, state.blkIndent, false) - const data = parseYaml(yaml) - const token = state.env.comarkBlockTokens[0] - Object.entries(data || {}).forEach(([key, value]) => { - if (key === 'class') { - token.attrJoin(key, value as string) - return - } - // Match @nuxtjs/mdc: non-string YAML values are stored as `:`-prefixed - // bindings with a JSON-string payload. Framework renderers (and - // resolveAttributes with parseJson) restore native types; quoted YAML - // strings stay unprefixed and remain strings (#364). - if (typeof value === 'string') { - token.attrSet(key, value) - } else { - token.attrSet(`:${key}`, JSON.stringify(value)) - } - }) - } - - state.line = lineEnd + 1 - return true - }) - - md.block.ruler.after( - 'code', - 'comark_block_slots', - function comark_block_slots(state, startLine, endLine, silent) { - if (!state.env.comarkBlockTokens?.length) return false - - const start = state.bMarks[startLine] + state.tShift[startLine] - - if (!(state.src[start] === '#' && state.src[start + 1] !== ' ' && state.src[start + 1] !== '#')) return false - - const line = state.src.slice(start, state.eMarks[startLine]) - - const slotParams = line.slice(1) - if (!isValidComponentName(slotParams.trimStart())) return false - const { name, props, remaining } = parseBlockParams(slotParams) - if (remaining) return false - - if (silent) return true - - let lineEnd = startLine + 1 - let inCodeFence = false - let codeFenceChar = '' - let codeFenceCount = 0 - while (lineEnd < endLine) { - const inner = state.src.slice(state.bMarks[lineEnd] + state.tShift[startLine], state.eMarks[lineEnd]) - - if (inCodeFence) { - // Look for matching closing fence (same char, >= opening count, nothing but spaces after) - if (inner[0] === codeFenceChar) { - let fencePos = 1 - while (fencePos < inner.length && inner[fencePos] === codeFenceChar) fencePos++ - if (fencePos >= codeFenceCount && inner.slice(fencePos).trim() === '') { - inCodeFence = false - } - } - lineEnd += 1 - continue - } - - // Detect opening code fence (``` or ~~~, length >= 3) - if (inner[0] === '`' || inner[0] === '~') { - const ch = inner[0] - let fencePos = 1 - while (fencePos < inner.length && inner[fencePos] === ch) fencePos++ - if (fencePos >= 3) { - inCodeFence = true - codeFenceChar = ch - codeFenceCount = fencePos - lineEnd += 1 - continue - } - } - - if (/^#\w+/.test(inner) || inner.startsWith('::')) break - lineEnd += 1 - } - - // Restore lineMax after tokenizing so it doesn't leak a narrower bound to - // whatever comes after this slot (see `comark_block`'s save/restore above). - const oldLineMax = state.lineMax - const slot = state.push('mdc_block_slot_open', 'template', 1) - slot.attrSet('name', `${name}`) - props?.forEach(([key, value]) => { - if (key === 'class') slot.attrJoin(key, value) - else slot.attrSet(key, value) - }) - - state.line = startLine + 1 - state.lineMax = lineEnd - - state.md.block.tokenize(state, startLine + 1, lineEnd) - - state.push('mdc_block_slot_close', 'template', -1) - - state.line = lineEnd - state.lineMax = oldLineMax - - return true - }, - { alt: ['paragraph'] } - ) -} - -const ALLOWED_PREV_CHARS = new Set([' ', '\t', '\n', '*', '_', '[', ']', '}', ')', '>']) - -const markdownItInlineComponent: PluginSimple = (md) => { - md.inline.ruler.after('entity', 'comark_inline_component', (state, silent) => { - const start = state.pos - if (state.src[start] !== ':') return false - - const prevChar = state.src[start - 1] - if (start > 0 && !ALLOWED_PREV_CHARS.has(prevChar)) return false - - let index = start + 1 - let nameEnd = -1 - let contentStart = -1 - let contentEnd = -1 - - while (index < state.src.length) { - const char = state.src[index] - if (char === '[') { - nameEnd = index - const result = parseBracketContent(state.src, index) - if (result) { - contentStart = index + 1 - contentEnd = result.endIndex - 1 - index = result.endIndex - } - break - } - if (!/[\w$-]/.test(char)) break - index += 1 - } - - if (nameEnd === -1) nameEnd = index - - // Empty name - if (nameEnd <= start + 1) return false - - const name = state.src.slice(start + 1, nameEnd) - if (!isValidComponentName(name)) return false - - state.pos = index - - if (silent) return true - - if (contentStart !== -1) { - state.push('mdc_inline_component_open', name, 1) - - const oldPos = state.pos - const oldPosMax = state.posMax - state.pos = contentStart - state.posMax = contentEnd - state.md.inline.tokenize(state) - state.pos = oldPos - state.posMax = oldPosMax - - state.push('mdc_inline_component_close', name, -1) - } else { - state.push('mdc_inline_component', name, 0) - } - - return true - }) -} - -// #region Inline span (`[text]` / `[text]{attrs}`) - -const markdownItInlineSpan: PluginSimple = (md) => { - md.inline.ruler.before('link', 'comark_inline_span', (state, silent) => { - const start = state.pos - if (state.src[start] !== '[') return false - - // An unclosed span consumes to the end of input (streaming auto-close) - const close = findClosingBracket(state.src, start) - const index = close === -1 ? state.src.length : close - - // Don't match `[text](url)` or `[text][ref]` — let the link parser handle those - const nextChar = state.src[index + 1] - if (nextChar === '(' || nextChar === '[') return false - - // Inside a link label, bare `[text]` stays literal (plain-markdown behavior, - // e.g. `[[1] Document](#)`); only an explicit `[text]{attrs}` span matches - if (state.linkLevel > 0 && nextChar !== '{') return false - - // Returning `false` lets `parseLinkLabel`'s own depth tracking consume nested brackets and the outer link parse - if (silent) return false - - state.push('mdc_inline_span_open', 'span', 1) - - const oldPos = state.pos - const oldPosMax = state.posMax - state.pos = start + 1 - state.posMax = index - state.md.inline.tokenize(state) - state.pos = oldPos - state.posMax = oldPosMax - - state.push('mdc_inline_span_close', 'span', -1) - - state.pos = index + 1 - - return true - }) -} - -// #endregion - -/** markdown-it / markdown-exit adapter for Comark component + span syntax. */ -export const markdownItComponents: PluginSimple = (md) => { - md.use(markdownItComarkBlock) - md.use(markdownItInlineSpan) - md.use(markdownItInlineComponent) -} +// Keep the import outside the plugin factory so TypeScript rewrites its extension. +const loadYaml = (): Promise => import('../internal/parse/yaml.ts') export default defineComarkPlugin(() => ({ name: 'components', - markdownItPlugins: [markdownItComponents as unknown as MarkdownItPlugin], + async prepare(state: Readonly): Promise { + if ( + !yaml && + (hasYamlProps(state.markdown) || + state.options.plugins?.some((plugin) => plugin.markdownItPlugins?.some((fn) => !isSourceStable(fn)))) + ) { + yaml = await loadYaml() + } + }, + markdownItPlugins: [markSourceStable(markdownItComponents as unknown as MarkdownItPlugin)], })) diff --git a/packages/comark/src/plugins/components/markdown-it.ts b/packages/comark/src/plugins/components/markdown-it.ts new file mode 100644 index 000000000..4ca0555a2 --- /dev/null +++ b/packages/comark/src/plugins/components/markdown-it.ts @@ -0,0 +1,5 @@ +/** Synchronous markdown-it / markdown-exit adapter for Comark component syntax. */ +import { createMarkdownItComponents } from '../../internal/parse/components.ts' +import { parseYaml } from '../../internal/parse/yaml.ts' + +export const markdownItComponents = createMarkdownItComponents(parseYaml) diff --git a/packages/comark/src/plugins/frontmatter.ts b/packages/comark/src/plugins/frontmatter.ts index ec9ebf42f..9e7adb472 100644 --- a/packages/comark/src/plugins/frontmatter.ts +++ b/packages/comark/src/plugins/frontmatter.ts @@ -18,16 +18,18 @@ * ``` */ +import type { ComarkParsePreState } from '../types.ts' import { defineComarkPlugin } from '../utils/helpers.ts' -// The YAML parser loads only for documents that start with frontmatter. -const loadFrontmatter = () => import('../internal/parse/frontmatter.ts') +// Keep the import outside the plugin factory so TypeScript rewrites its extension. +const loadYaml = (): Promise => + import('../internal/parse/frontmatter.ts') export default defineComarkPlugin(() => ({ name: 'frontmatter', - async pre(state) { + async pre(state: ComarkParsePreState): Promise { if (!state.markdown.startsWith('---')) return - const { parseFrontmatter } = await loadFrontmatter() + const { parseFrontmatter } = await loadYaml() const { content, data, frontmatterText } = parseFrontmatter(state.markdown) state.markdown = content state.frontmatter = data diff --git a/packages/comark/src/plugins/html.ts b/packages/comark/src/plugins/html.ts index 999f91696..08003ecd2 100644 --- a/packages/comark/src/plugins/html.ts +++ b/packages/comark/src/plugins/html.ts @@ -38,6 +38,7 @@ import { type StateBlock, Token, type MarkdownExit } from 'markdown-exit/core' import type { ComarkParseTokensState } from '../types.ts' import { defineComarkPlugin } from '../utils/helpers.ts' +import { markSourceStable } from '../internal/parse/source-stable.ts' export interface HtmlPluginOptions { /** @@ -52,7 +53,7 @@ export default defineComarkPlugin((opts: HtmlPluginOptions = {}) => { return { name: 'html', - markdownItPlugins: [markdown ? markdownItHtmlWithMarkdown : markdownItHtmlWithoutMarkdown], + markdownItPlugins: [markSourceStable(markdown ? markdownItHtmlWithMarkdown : markdownItHtmlWithoutMarkdown)], markdownItPost: markdownItPost, } }) diff --git a/packages/comark/src/plugins/linkify.ts b/packages/comark/src/plugins/linkify.ts index e2a32018f..0959e6967 100644 --- a/packages/comark/src/plugins/linkify.ts +++ b/packages/comark/src/plugins/linkify.ts @@ -11,6 +11,7 @@ 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' +import { markSourceStable } from '../internal/parse/source-stable.ts' /** * linkify-it recognition options. All default to linkify-it's own defaults: @@ -40,5 +41,5 @@ function markdownItLinkify(options: LinkifyPluginOptions): MarkdownItPlugin { export default defineComarkPlugin((options: LinkifyPluginOptions = {}) => ({ name: 'linkify', - markdownItPlugins: [markdownItLinkify(options)], + markdownItPlugins: [markSourceStable(markdownItLinkify(options))], })) diff --git a/packages/comark/src/plugins/task-list.ts b/packages/comark/src/plugins/task-list.ts index 4ff09e8d5..95ac7fc8c 100644 --- a/packages/comark/src/plugins/task-list.ts +++ b/packages/comark/src/plugins/task-list.ts @@ -6,6 +6,7 @@ */ import { defineComarkPlugin } from '../utils/helpers.ts' +import { markSourceStable } from '../internal/parse/source-stable.ts' interface MarkdownItToken { type: string @@ -178,5 +179,5 @@ function markdownItTaskList(md: MarkdownIt, options?: TaskListOptions) { } export default defineComarkPlugin(() => ({ name: 'task-list', - markdownItPlugins: [markdownItTaskList], + markdownItPlugins: [markSourceStable(markdownItTaskList)], })) diff --git a/packages/comark/src/types.ts b/packages/comark/src/types.ts index fd8dc3ce2..357a2cfc5 100644 --- a/packages/comark/src/types.ts +++ b/packages/comark/src/types.ts @@ -436,6 +436,8 @@ export type ComarkPlugin = { markdownItPlugins?: Array markdownItPost?: (state: ComarkParseTokensState) => void pre?: (state: ComarkParsePreState) => Promise | void + /** Prepare dependencies from the final markdown after all pre hooks finish. */ + prepare?: (state: Readonly) => Promise | void post?: (state: ComarkParsePostState, Writable>) => Promise | void /** Auto-close flags for syntax this plugin adds, applied when `autoClose` is `true`. */ autoClose?: Pick diff --git a/packages/comark/test/yaml-lazy-load.test.ts b/packages/comark/test/yaml-lazy-load.test.ts index 91ce30985..379a33421 100644 --- a/packages/comark/test/yaml-lazy-load.test.ts +++ b/packages/comark/test/yaml-lazy-load.test.ts @@ -1,6 +1,9 @@ import { execFileSync } from 'node:child_process' +import * as nodeModule from 'node:module' import { expect, it } from 'vitest' +const loadTest = it.skipIf(!('registerHooks' in nodeModule)) + // Runs `script` in a fresh Node process that records every js-yaml module it loads. function yamlLoads(script: string): string { return execFileSync( @@ -26,7 +29,7 @@ function yamlLoads(script: string): string { ) } -it('parses and renders a document without frontmatter or YAML attributes without loading YAML', () => { +loadTest('parses and renders a document without frontmatter or YAML attributes without loading YAML', () => { const result = yamlLoads(` const { createMarkdownParser } = await import('comark/core') const { default: frontmatter } = await import('comark/plugins/frontmatter') @@ -38,7 +41,7 @@ it('parses and renders a document without frontmatter or YAML attributes without expect(result).toBe('not loaded') }) -it('loads YAML for frontmatter and YAML attributes', () => { +loadTest('loads YAML for frontmatter and YAML attributes', () => { const result = yamlLoads(` const { createMarkdownParser } = await import('comark/core') const { default: frontmatter } = await import('comark/plugins/frontmatter') @@ -54,7 +57,133 @@ it('loads YAML for frontmatter and YAML attributes', () => { it('exports parseFrontmatter and renderFrontmatter from comark/frontmatter only', async () => { const entry = await import('comark/frontmatter') - expect(Object.keys(entry).sort()).toEqual(['parseFrontmatter', 'renderFrontmatter']) + expect(entry).toHaveProperty('parseFrontmatter') + expect(entry).toHaveProperty('renderFrontmatter') expect('parseFrontmatter' in (await import('comark'))).toBe(false) expect('renderFrontmatter' in (await import('comark/render'))).toBe(false) }) + +loadTest.each([ + '# Hello\n\nSome *text*', + '::card{title="Card"}\nBody\n::', + '::card\nBody\n\n---\n\nMore\n::', + 'Text\n\n---\n\nText', + '::card\n```yaml\nheight: 400\n```\n::', +])('keeps YAML unloaded with default plugins: %j', (source) => { + expect( + yamlLoads(` + const { parseMarkdown } = await import('comark') + const { renderMarkdown } = await import('comark/render') + await renderMarkdown(await parseMarkdown(${JSON.stringify(source)})) + `) + ).toBe('not loaded') +}) + +const yamlProps = 'title: Card\nheight: 400\n' +const frontmatterCard = `::card\n---\n${yamlProps}---\nBody\n::` +const propsCases = [ + frontmatterCard, + frontmatterCard.replaceAll('\n', '\r\n'), + frontmatterCard.replaceAll('\n', '\r'), + frontmatterCard + .split('\n') + .map((line) => ` ${line}`) + .join('\n'), + ` ::card\n---\n${yamlProps}---\nBody\n ::`, + `::outer\n${frontmatterCard}\n::`, + frontmatterCard + .split('\n') + .map((line) => `> ${line}`) + .join('\n'), + `- ${frontmatterCard.replaceAll('\n', '\n ')}`, + frontmatterCard.replace('::card', '::: card').replace(/::$/, ':::'), +] +for (const fence of ['```', '~~~']) { + for (const language of ['yaml', 'yml']) { + propsCases.push(`::card\n${fence}${language} [props]\n${yamlProps}${fence}\nBody\n::`) + } +} + +loadTest.each(propsCases)('loads and preserves component YAML props: %j', (source) => { + expect( + yamlLoads(` + const { parseMarkdown } = await import('comark') + assert.equal(yamlLoaded, false) + const { visit } = await import('comark/utils') + const tree = await parseMarkdown(${JSON.stringify(source)}) + let found = false + visit(tree, node => Array.isArray(node) && node[0] === 'card', node => { + found = true + assert.equal(node[1].title, 'Card') + assert.equal(node[1][':height'], '400') + }) + assert.equal(found, true) + `) + ).toBe('loaded') +}) + +loadTest('loads component YAML when a streaming props block becomes complete', () => { + expect( + yamlLoads(` + const { createMarkdownParser } = await import('comark') + const parse = createMarkdownParser() + await parse('::card\\nBody', { streaming: true }) + assert.equal(yamlLoaded, false) + const tree = await parse(${JSON.stringify(frontmatterCard)}, { streaming: true }) + assert.equal(tree.nodes[0][0], 'card') + assert.equal(tree.nodes[0][1][':height'], '400') + `) + ).toBe('loaded') +}) + +it('keeps the markdown-it adapter synchronous at its dedicated entry', async () => { + const { default: MarkdownIt } = await import('markdown-it') + const { markdownItComponents } = await import('comark/plugins/components/markdown-it') + const tokens = new MarkdownIt().use(markdownItComponents).parse(frontmatterCard, {}) + const card = tokens.find((token) => token.tag === 'card' && token.nesting === 1) + expect(card?.attrGet('title')).toBe('Card') + expect(card?.attrGet(':height')).toBe('400') +}) + +loadTest.each([false, true])('prepares component YAML after source transforms, streaming=%j', (streaming) => { + expect( + yamlLoads(` + const { createMarkdownParser } = await import('comark') + const parse = createMarkdownParser({ plugins: [{ + name: 'strip-comments', + async pre(state) { + await Promise.resolve() + state.markdown = state.markdown.replaceAll('', '') + }, + }] }) + if (${streaming}) await parse('# Before', { streaming: true }) + assert.equal(yamlLoaded, false) + const tree = await parse(${JSON.stringify(frontmatterCard.replace('---', '---'))}, { streaming: ${streaming} }) + assert.equal(tree.nodes[0][0], 'card') + assert.equal(tree.nodes[0][1].title, 'Card') + assert.equal(tree.nodes[0][1][':height'], '400') + `) + ).toBe('loaded') +}) + +loadTest.each([false, true])('supports markdown-it source transforms, streaming=%j', (streaming) => { + expect( + yamlLoads(` + const { createMarkdownParser } = await import('comark') + const parse = createMarkdownParser({ plugins: [{ + name: 'include', + markdownItPlugins: [md => { + md.core.ruler.before('block', 'include', state => { + if (state.src === '{{include}}') state.src = ${JSON.stringify(frontmatterCard)} + }) + }], + }] }) + assert.equal(yamlLoaded, false) + if (${streaming}) await parse('# Before', { streaming: true }) + const tree = await parse('{{include}}', { streaming: ${streaming} }) + assert.equal(tree.nodes[0][0], 'card') + assert.equal(tree.nodes[0][1].title, 'Card') + assert.equal(tree.nodes[0][1][':height'], '400') + `) + ).toBe('loaded') +}) diff --git a/patches/comark-content@0.4.3.patch b/patches/comark-content@0.4.3.patch new file mode 100644 index 000000000..48dfca735 --- /dev/null +++ b/patches/comark-content@0.4.3.patch @@ -0,0 +1,21 @@ +diff --git a/dist/plugins/markdown.js b/dist/plugins/markdown.js +index 512aa963f44fecdc0f720a6817f153d498dd3667..e04df92468c95279f4e7c47f6d6c92ed0483ad5c 100644 +--- a/dist/plugins/markdown.js ++++ b/dist/plugins/markdown.js +@@ -1,4 +1,5 @@ +-import { createMarkdownParser, parseFrontmatter, } from 'comark'; ++import { createMarkdownParser } from 'comark'; ++import { parseFrontmatter } from 'comark/frontmatter'; + export default function markdown(options = {}) { + return { + name: 'markdown', +diff --git a/dist/plugins/yaml.js b/dist/plugins/yaml.js +index 6c31d008b62a8f2c86d2cc5fb92b5f426b952701..a4a002e52dc235eec0084651851427ecb3b3daac 100644 +--- a/dist/plugins/yaml.js ++++ b/dist/plugins/yaml.js +@@ -1,4 +1,4 @@ +-import { parseFrontmatter } from 'comark'; ++import { parseFrontmatter } from 'comark/frontmatter'; + import { defineContentPlugin } from '../utils/plugin.js'; + import { handleParseError } from '../utils/on-error.js'; + export default defineContentPlugin((options = {}) => ({ diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 555b0f842..5236f19b1 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -468,6 +468,7 @@ overrides: '@comark/vue': workspace:* patchedDependencies: + comark-content@0.4.3: 85d996a86358d70d44242740b4e5e73ff28305c17a315b98f371f082ed8ca2c3 minimark: 1e0eaaab5c9ffee4dcf68d6e89d35546917e9c8033757789e7675f1a2ea323a9 importers: @@ -15193,7 +15194,7 @@ snapshots: colortranslator@5.0.0: {} - comark-content@0.4.3(@vercel/functions@3.10.3(ws@8.22.0))(db0@0.3.4)(forges@0.3.1)(ioredis@5.11.1(supports-color@10.2.2)): + comark-content@0.4.3(patch_hash=85d996a86358d70d44242740b4e5e73ff28305c17a315b98f371f082ed8ca2c3)(@vercel/functions@3.10.3(ws@8.22.0))(db0@0.3.4)(forges@0.3.1)(ioredis@5.11.1(supports-color@10.2.2)): dependencies: citty: 0.2.2 comark: link:packages/comark @@ -15257,7 +15258,7 @@ snapshots: ai: 7.0.159(zod@4.6.7) beautiful-mermaid: 1.1.3 comark: link:packages/comark - comark-content: 0.4.3(@vercel/functions@3.10.3(ws@8.22.0))(db0@0.3.4)(forges@0.3.1)(ioredis@5.11.1(supports-color@10.2.2)) + comark-content: 0.4.3(patch_hash=85d996a86358d70d44242740b4e5e73ff28305c17a315b98f371f082ed8ca2c3)(@vercel/functions@3.10.3(ws@8.22.0))(db0@0.3.4)(forges@0.3.1)(ioredis@5.11.1(supports-color@10.2.2)) defu: 6.1.7 exsolve: 1.2.0 forges: 0.3.1 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 606dffe58..5ec6f15db 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -194,4 +194,5 @@ minimumReleaseAgeExclude: - markdown-exit@2.1.0 patchedDependencies: + comark-content@0.4.3: patches/comark-content@0.4.3.patch minimark: patches/minimark.patch diff --git a/test/bundle.test.ts b/test/bundle.test.ts index f236b3741..46931ba97 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": "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": "421k (167 files)", + "@comark/angular": "60.2k (81 files)", + "@comark/ansi": "39.1k (107 files)", + "@comark/html": "17.4k (67 files)", + "@comark/nuxt": "13.6k (67 files)", + "@comark/react": "43.0k (85 files)", + "@comark/svelte": "50.4k (93 files)", + "@comark/vue": "60.3k (89 files)", + "comark": "426k (179 files)", } `) }) From 9fee4c5dd92dd780759f4808e643a404847785d1 Mon Sep 17 00:00:00 2001 From: onmax Date: Fri, 6 Nov 2026 14:25:17 +0100 Subject: [PATCH 3/5] fix(plugins): keep YAML lazy with source-stable built-ins --- AGENTS.md | 2 +- docs/content/4.plugins/0.defaults/components.md | 2 +- packages/comark/src/plugins/binding.ts | 5 +++-- packages/comark/src/plugins/emoji.ts | 3 ++- packages/comark/src/plugins/math.ts | 4 ++-- packages/comark/src/plugins/mermaid.ts | 4 ++-- packages/comark/test/yaml-lazy-load.test.ts | 13 +++++++++++++ 7 files changed, 24 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8243a6460..b5bfa3b4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -599,7 +599,7 @@ import mermaid, { Mermaid } from '@comark/angular/plugins/mermaid' import binding, { Binding, If } from '@comark/angular/plugins/binding' ``` -Plugin `pre` hooks transform markdown in order. Async `prepare(state)` hooks run after all `pre` hooks and before tokenization, so syntax dependencies load for the final source and parser configuration. The components plugin uses `prepare` for YAML props, and preloads YAML for unrecognized markdown-it plugin functions that may generate props. Default rule functions are registered as source-stable in `internal/parse/source-stable.ts`; its synchronous markdown-it adapter lives at `comark/plugins/components/markdown-it` and imports YAML eagerly. +Plugin `pre` hooks transform markdown in order. Async `prepare(state)` hooks run after all `pre` hooks and before tokenization, so syntax dependencies load for the final source and parser configuration. The components plugin uses `prepare` for YAML props, and preloads YAML for unrecognized markdown-it plugin functions that may generate props. Default rule functions and the built-in `emoji`, `math`, `mermaid` and `binding` rule functions are registered as source-stable in `internal/parse/source-stable.ts`; its synchronous markdown-it adapter lives at `comark/plugins/components/markdown-it` and imports YAML eagerly. ## Coding Principles diff --git a/docs/content/4.plugins/0.defaults/components.md b/docs/content/4.plugins/0.defaults/components.md index 4368f215a..9a13cfd11 100644 --- a/docs/content/4.plugins/0.defaults/components.md +++ b/docs/content/4.plugins/0.defaults/components.md @@ -103,7 +103,7 @@ When the components plugin is not active, `autoClose` also skips component-fence For hosts that use markdown-it or markdown-exit directly (for example VitePress), use the exported adapter: -With Comark's default rules, YAML loads only when the source may contain component props. Additional markdown-it plugins can generate props during synchronous tokenization, so an unrecognized markdown-it plugin makes YAML load before parsing. The synchronous markdown-it adapter imports YAML eagerly and has its own entry, `comark/plugins/components/markdown-it`. Move named adapter imports from `comark/plugins/components` to this path. +With Comark's default rules and the built-in `emoji`, `math`, `mermaid` and `binding` plugins, YAML loads only when the source may contain component props. Additional markdown-it plugins can generate props during synchronous tokenization, so an unrecognized markdown-it plugin makes YAML load before parsing. The synchronous markdown-it adapter imports YAML eagerly and has its own entry, `comark/plugins/components/markdown-it`. Move named adapter imports from `comark/plugins/components` to this path. ```typescript import { markdownItComponents } from 'comark/plugins/components/markdown-it' diff --git a/packages/comark/src/plugins/binding.ts b/packages/comark/src/plugins/binding.ts index 9b07b551d..8e0dff596 100644 --- a/packages/comark/src/plugins/binding.ts +++ b/packages/comark/src/plugins/binding.ts @@ -1,6 +1,7 @@ import type { PluginWithOptions, MarkdownExit } from 'markdown-exit/core' import { defineComarkPlugin } from 'comark' -import type { MarkdownItPlugin, NodeHandler, Node } from 'comark' +import type { NodeHandler, Node } from 'comark' +import { markSourceStable } from '../internal/parse/source-stable.ts' export interface MdcInlineBindingOptions { /** @@ -144,7 +145,7 @@ const markdownItInlineBinding: PluginWithOptions = (md, export default defineComarkPlugin((opts: MdcInlineBindingOptions = {}) => { return { name: 'binding', - markdownItPlugins: [((md: MarkdownExit) => markdownItInlineBinding(md, opts)) as unknown as MarkdownItPlugin], + markdownItPlugins: [markSourceStable((md: MarkdownExit) => markdownItInlineBinding(md, opts))], } }) diff --git a/packages/comark/src/plugins/emoji.ts b/packages/comark/src/plugins/emoji.ts index c05931f17..badfd29a0 100644 --- a/packages/comark/src/plugins/emoji.ts +++ b/packages/comark/src/plugins/emoji.ts @@ -1,5 +1,6 @@ import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from 'comark' +import { markSourceStable } from '../internal/parse/source-stable.ts' // Curated set of common emoji shortcodes, organized by category. // For the full GitHub set, install a dataset (e.g. `gemoji`) and pass it via @@ -506,6 +507,6 @@ export default defineComarkPlugin((options) => { return { name: 'emoji', - markdownItPlugins: [markdownItPlugin], + markdownItPlugins: [markSourceStable(markdownItPlugin)], } }) diff --git a/packages/comark/src/plugins/math.ts b/packages/comark/src/plugins/math.ts index 40fccfe3f..a02cffd1c 100644 --- a/packages/comark/src/plugins/math.ts +++ b/packages/comark/src/plugins/math.ts @@ -1,7 +1,7 @@ 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' +import { markSourceStable } from '../internal/parse/source-stable.ts' export interface MathConfig { /** @@ -415,6 +415,6 @@ function markdownItMath(md: MarkdownExit, config: MathConfig = {}) { */ export default defineComarkPlugin((config: MathConfig = {}) => ({ name: 'math', - markdownItPlugins: [((md: MarkdownExit) => markdownItMath(md, config)) as unknown as MarkdownItPlugin], + markdownItPlugins: [markSourceStable((md: MarkdownExit) => markdownItMath(md, config))], autoClose: config.brackets ? { bracketMath: true } : undefined, })) diff --git a/packages/comark/src/plugins/mermaid.ts b/packages/comark/src/plugins/mermaid.ts index c0b85973e..5b3082fe3 100644 --- a/packages/comark/src/plugins/mermaid.ts +++ b/packages/comark/src/plugins/mermaid.ts @@ -1,6 +1,6 @@ import type { MarkdownExit } from 'markdown-exit/core' -import type { MarkdownItPlugin } from 'comark' import { defineComarkPlugin } from 'comark' +import { markSourceStable } from '../internal/parse/source-stable.ts' export type ThemeNames = | 'zinc-light' @@ -206,5 +206,5 @@ export function searchProps(content: string, index = 0) { */ export default defineComarkPlugin((config: MermaidConfig = {}) => ({ name: 'mermaid', - markdownItPlugins: [((md: MarkdownExit) => markdownItMermaid(md, config)) as unknown as MarkdownItPlugin], + markdownItPlugins: [markSourceStable((md: MarkdownExit) => markdownItMermaid(md, config))], })) diff --git a/packages/comark/test/yaml-lazy-load.test.ts b/packages/comark/test/yaml-lazy-load.test.ts index 379a33421..df0022002 100644 --- a/packages/comark/test/yaml-lazy-load.test.ts +++ b/packages/comark/test/yaml-lazy-load.test.ts @@ -79,6 +79,19 @@ loadTest.each([ ).toBe('not loaded') }) +loadTest.each(['emoji', 'math', 'mermaid', 'binding'])('keeps YAML unloaded with components and %s', (name) => { + expect( + yamlLoads(` + const { createMarkdownParser } = await import('comark/core') + const { default: components } = await import('comark/plugins/components') + const { default: plugin } = await import('comark/plugins/${name}') + const parse = createMarkdownParser({ plugins: [plugin(), components()] }) + assert.equal(yamlLoaded, false) + assert.deepEqual((await parse('Hello')).nodes, [['p', {}, 'Hello']]) + `) + ).toBe('not loaded') +}) + const yamlProps = 'title: Card\nheight: 400\n' const frontmatterCard = `::card\n---\n${yamlProps}---\nBody\n::` const propsCases = [ From 0468bd4a4dc4f43f8f73495e885110c182ffc45c Mon Sep 17 00:00:00 2001 From: onmax Date: Fri, 6 Nov 2026 17:25:14 +0100 Subject: [PATCH 4/5] docs(components): point reused component rules at the markdown-it adapter Name the adapter entry in the error thrown when component rules tokenize YAML props without the plugin's prepare hook, list every source-stable built-in, and drop text that still said the parser loads YAML eagerly. --- AGENTS.md | 8 +++++--- docs/content/3.rendering/2.html.md | 2 +- docs/content/4.plugins/0.defaults/components.md | 6 +++--- packages/comark/src/plugins/components.ts | 6 +++++- packages/comark/src/plugins/frontmatter.ts | 4 ++-- 5 files changed, 16 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b5bfa3b4c..094b865e0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,6 +69,7 @@ packages/comark/ │ │ ├── frontmatter.ts # YAML frontmatter extraction (default via registerDefaultPlugins) │ │ ├── html.ts # HTML block/inline parsing (default via registerDefaultPlugins) │ │ ├── components.ts # prepare() loads YAML after all pre hooks; loader for block/inline components + spans (`::name`, `:name`, `[text]`) +│ │ ├── components/markdown-it.ts # Synchronous markdownItComponents adapter (imports YAML eagerly) │ │ ├── attributes.ts # Inline attributes (`{props}` after tokens) │ │ ├── binding.ts # Inline interpolation + shared conditional rendering rules │ │ ├── breaks.ts # Hard line breaks (`
`) from newlines @@ -106,6 +107,7 @@ packages/comark/ │ │ ├── components.ts # Shared component rules and YAML detection; the synchronous adapter lives in plugins/components/markdown-it.ts │ │ ├── frontmatter.ts # parseFrontmatter() │ │ ├── yaml.ts # parseYaml() +│ │ ├── source-stable.ts # Built-in rule functions that can't add YAML props during tokenization │ │ ├── auto-close/ # Self-healing for incomplete markdown │ │ ├── html/ # HTML block/inline rules │ │ ├── syntax/ # Component syntax scanners (props, brackets, block params) @@ -188,7 +190,7 @@ const html = await renderHtml(markdownString) --- -`@comark/html` renders through `comark/render/html`, which registers only the HTML and comment handlers, so rendering never loads the Markdown serializers. `@comark/html/render` also stays free of YAML; the root entry and the plugins import the parser, which loads YAML for frontmatter. Components still receive the full `state`, but `state.handlers` holds only `html` and `comment`, and the output format is always `text/html`. Both `comark/render` and `comark/render/html` share the engine in `internal/stringify/state.ts`; each passes its own handler map to `createState`. HTML-safe attribute handling lives in `html-attributes.ts`; Markdown/YAML attribute serialization stays in `attributes.ts`. +`@comark/html` renders through `comark/render/html`, which registers only the HTML and comment handlers, so rendering never loads the Markdown serializers. `@comark/html/render` also stays free of YAML; the root entry and the plugins import the parser, which loads YAML on first use, for frontmatter or component props. Components still receive the full `state`, but `state.handlers` holds only `html` and `comment`, and the output format is always `text/html`. Both `comark/render` and `comark/render/html` share the engine in `internal/stringify/state.ts`; each passes its own handler map to `createState`. HTML-safe attribute handling lives in `html-attributes.ts`; Markdown/YAML attribute serialization stays in `attributes.ts`. ## Package: @comark/ansi @@ -599,7 +601,7 @@ import mermaid, { Mermaid } from '@comark/angular/plugins/mermaid' import binding, { Binding, If } from '@comark/angular/plugins/binding' ``` -Plugin `pre` hooks transform markdown in order. Async `prepare(state)` hooks run after all `pre` hooks and before tokenization, so syntax dependencies load for the final source and parser configuration. The components plugin uses `prepare` for YAML props, and preloads YAML for unrecognized markdown-it plugin functions that may generate props. Default rule functions and the built-in `emoji`, `math`, `mermaid` and `binding` rule functions are registered as source-stable in `internal/parse/source-stable.ts`; its synchronous markdown-it adapter lives at `comark/plugins/components/markdown-it` and imports YAML eagerly. +Plugin `pre` hooks transform markdown in order. Async `prepare(state)` hooks run after all `pre` hooks and before tokenization, so syntax dependencies load for the final source and parser configuration. The components plugin uses `prepare` for YAML props, and preloads YAML for unrecognized markdown-it plugin functions that may generate props. The built-in rule functions (`components`, `attributes`, `html`, `task-list`, `linkify`, `emoji`, `math`, `mermaid` and `binding`) are registered as source-stable in `internal/parse/source-stable.ts`; its synchronous markdown-it adapter lives at `comark/plugins/components/markdown-it` and imports YAML eagerly. ## Coding Principles @@ -742,7 +744,7 @@ lossless through `parseMarkdown` → `renderMarkdown`: **Parse — dedent the children, don't raise the floor.** A child indented *less* than its own component marker is never dropped. Each child line is shifted left by `min(markerIndent, its own indentation)` and the region is tokenized against -a zero floor (`comark_block` in `src/plugins/components.ts` via +a zero floor (`comark_block` in `src/internal/parse/components.ts` via `src/internal/parse/indent.ts`, mirroring the line-mark mutation `blockquote` uses to strip its markers). Lines inside a fenced code block all take the *opening fence's* shift, so the fence and its diff --git a/docs/content/3.rendering/2.html.md b/docs/content/3.rendering/2.html.md index c24e91266..fe955c2ea 100644 --- a/docs/content/3.rendering/2.html.md +++ b/docs/content/3.rendering/2.html.md @@ -23,7 +23,7 @@ The `@comark/html` package parses Markdown or renders an existing `MarkdownDocum `@comark/html` renders HTML without loading the Markdown serializers. Components receive the renderer `state`, but `state.handlers` only contains the `html` and `comment` handlers, and the output is always HTML. To render a document back to Markdown, use `render` or `renderMarkdown` from `comark/render`. -If you already have a parsed document, import from `@comark/html/render`. It leaves out the parser, so it doesn't load YAML either: +If you already have a parsed document, import from `@comark/html/render`. It leaves out the parser: ```ts import { renderHtmlFromDocument } from '@comark/html/render' diff --git a/docs/content/4.plugins/0.defaults/components.md b/docs/content/4.plugins/0.defaults/components.md index 9a13cfd11..dcc9c96b5 100644 --- a/docs/content/4.plugins/0.defaults/components.md +++ b/docs/content/4.plugins/0.defaults/components.md @@ -99,11 +99,11 @@ const result = await parseMarkdown(content, { registerDefaultPlugins: false }) When the components plugin is not active, `autoClose` also skips component-fence completion (`::` closers). -## markdown-it / markdown-exit adapter +The parser loads YAML only when the source may contain component props. A markdown-it plugin that Comark doesn't ship can add props during tokenization, so registering one makes YAML load before parsing. -For hosts that use markdown-it or markdown-exit directly (for example VitePress), use the exported adapter: +## markdown-it / markdown-exit adapter -With Comark's default rules and the built-in `emoji`, `math`, `mermaid` and `binding` plugins, YAML loads only when the source may contain component props. Additional markdown-it plugins can generate props during synchronous tokenization, so an unrecognized markdown-it plugin makes YAML load before parsing. The synchronous markdown-it adapter imports YAML eagerly and has its own entry, `comark/plugins/components/markdown-it`. Move named adapter imports from `comark/plugins/components` to this path. +For hosts that use markdown-it or markdown-exit directly (for example VitePress), use the adapter from `comark/plugins/components/markdown-it`. It imports YAML eagerly, so it works without Comark's parser. Move named adapter imports from `comark/plugins/components` to this path, and use it instead of passing `components().markdownItPlugins` to another parser: those rules need the plugin's `prepare` hook to load YAML first. ```typescript import { markdownItComponents } from 'comark/plugins/components/markdown-it' diff --git a/packages/comark/src/plugins/components.ts b/packages/comark/src/plugins/components.ts index 7ba4e0d98..beeab2691 100644 --- a/packages/comark/src/plugins/components.ts +++ b/packages/comark/src/plugins/components.ts @@ -16,7 +16,11 @@ import { createMarkdownItComponents, hasYamlProps } from '../internal/parse/comp let yaml: typeof import('../internal/parse/yaml.ts') | undefined const markdownItComponents = createMarkdownItComponents((content) => { - if (!yaml) throw new Error('Component YAML props were not loaded before tokenization') + if (!yaml) { + throw new Error( + "Component YAML props were not loaded before tokenization. Register components() with createMarkdownParser, or use markdownItComponents from 'comark/plugins/components/markdown-it' with your own markdown-it instance." + ) + } return yaml.parseYaml(content) }) diff --git a/packages/comark/src/plugins/frontmatter.ts b/packages/comark/src/plugins/frontmatter.ts index 9e7adb472..ae3d67cae 100644 --- a/packages/comark/src/plugins/frontmatter.ts +++ b/packages/comark/src/plugins/frontmatter.ts @@ -22,14 +22,14 @@ import type { ComarkParsePreState } from '../types.ts' import { defineComarkPlugin } from '../utils/helpers.ts' // Keep the import outside the plugin factory so TypeScript rewrites its extension. -const loadYaml = (): Promise => +const loadFrontmatter = (): Promise => import('../internal/parse/frontmatter.ts') export default defineComarkPlugin(() => ({ name: 'frontmatter', async pre(state: ComarkParsePreState): Promise { if (!state.markdown.startsWith('---')) return - const { parseFrontmatter } = await loadYaml() + const { parseFrontmatter } = await loadFrontmatter() const { content, data, frontmatterText } = parseFrontmatter(state.markdown) state.markdown = content state.frontmatter = data From 0e0280a88f649630948fbb6a13c3710ef8e14918 Mon Sep 17 00:00:00 2001 From: onmax Date: Fri, 6 Nov 2026 21:45:39 +0100 Subject: [PATCH 5/5] perf(components): find YAML props by jumping between component openers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit hasYamlProps ran on every parse that hadn't loaded YAML yet and checked every character of every line, which cost about 23 µs on the adversarial bench document and 107 µs on the large one. Jump between `::` matches with indexOf instead, and check `[props]` fences with includes. It can still report props the tokenizer rejects, which only loads YAML early. --- .../comark/src/internal/parse/components.ts | 51 +++++++++---------- 1 file changed, 25 insertions(+), 26 deletions(-) diff --git a/packages/comark/src/internal/parse/components.ts b/packages/comark/src/internal/parse/components.ts index 7731768e1..272363690 100644 --- a/packages/comark/src/internal/parse/components.ts +++ b/packages/comark/src/internal/parse/components.ts @@ -510,35 +510,34 @@ export function createMarkdownItComponents(parseYaml: typeof import('./yaml.ts') } } -const blockYamlFences = Object.keys(blockYamlLines) +function lineEnd(source: string, pos: number): number { + while (pos < source.length && source[pos] !== '\n' && source[pos] !== '\r') pos++ + return pos +} -// Container prefixes and indentation are stripped during tokenization. Matching -// line suffixes here also covers YAML props inside lists and blockquotes. +// May report props that tokenization later rejects, which only loads YAML early; +// it must never miss props `comark_block_yaml` would parse. Container prefixes +// and indentation are stripped during tokenization, so lines are matched by suffix. export function hasYamlProps(source: string): boolean { - if (!source.includes('::')) return false - let previousComponent = false - for (let start = 0; start < source.length;) { - let end = start - while (end < source.length && source[end] !== '\n' && source[end] !== '\r') end++ - - for (const fence of blockYamlFences) { - if (fence === '---' && !previousComponent) continue - if (end - start >= fence.length && source.endsWith(fence, end)) return true - } - - previousComponent = false - for (let pos = start; pos < end; pos++) { - if (source[pos] !== ':' || source[pos + 1] !== ':') continue - while (pos < end && source[pos] === ':') pos++ - while (pos < end && (source[pos] === ' ' || source[pos] === '\t')) pos++ - const code = source.charCodeAt(pos) | 32 - if (pos < end && ((code >= 97 && code <= 122) || source[pos] === '$')) { - previousComponent = true - break - } + let pos = source.indexOf('::') + if (pos === -1) return false + // Every ```/~~~ yaml or yml `[props]` fence contains one of these. + if (source.includes('yaml [props]') || source.includes('yml [props]')) return true + while (pos !== -1) { + pos += 2 + while (source[pos] === ':') pos++ + while (source[pos] === ' ' || source[pos] === '\t') pos++ + const code = source.charCodeAt(pos) | 32 + if ((code >= 97 && code <= 122) || source[pos] === '$') { + // A `---` props fence must be the line right after the opener. + const end = lineEnd(source, pos) + if (end === source.length) return false + const next = end + (source[end] === '\r' && source[end + 1] === '\n' ? 2 : 1) + const nextEnd = lineEnd(source, next) + if (nextEnd - next >= 3 && source.endsWith('---', nextEnd)) return true + pos = next } - - start = end + (source[end] === '\r' && source[end + 1] === '\n' ? 2 : 1) + pos = source.indexOf('::', pos) } return false }