diff --git a/AGENTS.md b/AGENTS.md
index 20375c20b..094b865e0 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)
@@ -67,7 +68,8 @@ 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]`)
+│ │ ├── 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
@@ -98,12 +100,14 @@ 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
+│ │ ├── 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)
@@ -111,7 +115,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 +135,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"
}
@@ -185,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
@@ -483,6 +488,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'
@@ -545,7 +553,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.
@@ -593,6 +601,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. 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
### Performance First
@@ -734,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/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/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/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..dcc9c96b5 100644
--- a/docs/content/4.plugins/0.defaults/components.md
+++ b/docs/content/4.plugins/0.defaults/components.md
@@ -99,12 +99,14 @@ const result = await parseMarkdown(content, { registerDefaultPlugins: false })
When the components plugin is not active, `autoClose` also skips component-fence completion (`::` closers).
+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.
+
## markdown-it / markdown-exit adapter
-For hosts that use markdown-it or markdown-exit directly (for example VitePress), use the exported adapter:
+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'
+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/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/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/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/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/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/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
new file mode 100644
index 000000000..8e115a1cb
--- /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\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/parse/components.ts b/packages/comark/src/internal/parse/components.ts
new file mode 100644
index 000000000..272363690
--- /dev/null
+++ b/packages/comark/src/internal/parse/components.ts
@@ -0,0 +1,543 @@
+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)
+ }
+}
+
+function lineEnd(source: string, pos: number): number {
+ while (pos < source.length && source[pos] !== '\n' && source[pos] !== '\r') pos++
+ return pos
+}
+
+// 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 {
+ 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
+ }
+ pos = source.indexOf('::', pos)
+ }
+ return false
+}
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/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/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..366022749 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,10 +127,10 @@ 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'
-) {
+): 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.
@@ -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 7cc1d6381..b6c0b726e 100644
--- a/packages/comark/src/internal/stringify/handlers/mdc.ts
+++ b/packages/comark/src/internal/stringify/handlers/mdc.ts
@@ -57,7 +57,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/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/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/components.ts b/packages/comark/src/plugins/components.ts
index 9e2abcf9c..beeab2691 100644
--- a/packages/comark/src/plugins/components.ts
+++ b/packages/comark/src/plugins/components.ts
@@ -8,518 +8,35 @@
* @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/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. Register components() with createMarkdownParser, or use markdownItComponents from 'comark/plugins/components/markdown-it' with your own markdown-it instance."
+ )
+ }
+ 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/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/frontmatter.ts b/packages/comark/src/plugins/frontmatter.ts
index 420db77ec..ae3d67cae 100644
--- a/packages/comark/src/plugins/frontmatter.ts
+++ b/packages/comark/src/plugins/frontmatter.ts
@@ -18,12 +18,18 @@
* ```
*/
+import type { ComarkParsePreState } from '../types.ts'
import { defineComarkPlugin } from '../utils/helpers.ts'
-import { parseFrontmatter } from '../internal/frontmatter.ts'
+
+// Keep the import outside the plugin factory so TypeScript rewrites its extension.
+const loadFrontmatter = (): Promise =>
+ import('../internal/parse/frontmatter.ts')
export default defineComarkPlugin(() => ({
name: 'frontmatter',
- pre(state) {
+ async pre(state: ComarkParsePreState): Promise {
+ 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/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/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/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/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/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/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/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/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..df0022002
--- /dev/null
+++ b/packages/comark/test/yaml-lazy-load.test.ts
@@ -0,0 +1,202 @@
+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(
+ 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' }
+ )
+}
+
+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')
+ 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')
+})
+
+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')
+ 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(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')
+})
+
+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 = [
+ 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/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', () => {
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 d01257a0d..d32645955 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:
@@ -15201,7 +15202,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
@@ -15265,7 +15266,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 01f56c4d2..dfc6afd96 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": "424k (169 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": "429k (181 files)",
}
`)
})