` inside a list item or a blockquote that holds a single paragraph. - **`headingIds`** adds an `id` to every heading. ### Document model - **Tight and loose lists** aren't distinguished. List items render the same way with or without blank lines between them. - **Empty link text** removes the link: `[](/url)` renders nothing. - **Image alt text** keeps the raw Markdown: `` gives the alt text `foo *bar*`. - **Markdown inside an HTML block**, such as a `
` element. ### GFM extensions - **Email autolinks** such as `foo@bar.baz` stay plain text. URL autolinks such as `www.example.com` work. - **The tag filter** isn't applied: raw ``, `<style>`, `<xmp>` and the other filtered tags aren't escaped. Set `blockedTags` in the [security plugin](https://comark.dev/plugins/built-in/security) to remove them. --- - [Frontmatter](https://comark.dev/syntax/frontmatter) - [Components](https://comark.dev/syntax/components) # Components in Markdown: Block and Inline Syntax > Embed custom components directly in your Markdown with block and inline syntax, props, slots, and nested children. Comark extends standard Markdown with component syntax, letting you embed custom UI directly in your content while keeping it readable. Parsing is provided by the built-in [`components` plugin](https://comark.dev/plugins/defaults/components) (enabled by default). ::callout Comark also supports JSON-render syntax in code blocks — see the [json-render plugin](https://comark.dev/plugins/built-in/json-render). :: ## Block Block components use the `::component-name` syntax and occupy their own line: ```mdc ::component-name{prop1="value1" prop2="value2"} Content inside the component Can have **markdown** and other elements :: ``` Here are some examples of block components: ::code-group ```mdc [Alert] ::alert{type="info"} This is an important message! :: ``` ```mdc [Card] ::card{title="My Card"} Card content with **markdown** support :: ``` ```mdc [Empty] ::divider :: ``` :: ## Inline Inline components use the `:component-name` syntax and can be placed within text: ```mdc Check out this :icon-star component in the middle of text. Click the :button[Submit]{type="primary"} to continue. The status is :badge[Active]{color="green"} right now. ``` | Syntax | Description | | ----------------------------- | -------------------------------------------- | | `:icon-check` | Standalone inline component | | `:badge[New]` | Inline component with content | | `:badge[New]{color="blue"}` | Inline component with content and properties | | `:tooltip{text="Hover text"}` | Inline component with properties only | ## Properties Components support two property syntaxes: inline attributes and YAML frontmatter. ### Inline attributes Use the `{...}` syntax for scalar properties: ```mdc ::component{prop="value"} <!-- Standard key-value pair --> :: ::component{bool} <!-- Boolean property (becomes :bool="true" in AST) --> :: ::component{#custom-id} <!-- ID attribute --> :: ::component{.class-name} <!-- CSS class --> :: ::component{.class-one .class-two} <!-- Multiple CSS classes --> :: ::component{obj='{"key": "value"}'} <!-- Object/JSON value --> :: ::component{multiple="props" bool #id .class} <!-- Multiple properties combined --> :: ``` ### Block props For components with many properties, use YAML block syntax inside the component. Two styles are supported: ::code-group ~~~mdc [Codeblock Style] ::component ```yaml [props] title: My Component type: info count: 42 enabled: true items: - First item - Second item config: theme: dark mode: auto ``` Component content goes here With full **markdown** support :: ~~~ ```mdc [Frontmatter Style] ::component --- title: My Component type: info count: 42 enabled: true items: - First item - Second item config: theme: dark mode: auto --- Component content goes here With full **markdown** support :: ``` :: ::callout{color="info" icon="i-lucide-info"} Objects remain objects, arrays remain arrays, and numbers/booleans are parsed as their respective types rather than strings. Your components receive fully typed props. :: #### Key rules - Must be at the very beginning of the component content - Enclosed by `---` delimiters (frontmatter style) or `````yaml [props]`` fences (codeblock style) - Merged with inline attributes (YAML props take precedence, `class` values are merged) - Full support for complex data structures ::tip The default style can be configured with the [`blockAttributesStyle`](https://comark.dev/reference/render#options) option. :: ### Combine both syntaxes Inline attributes and YAML props can be combined. YAML props take precedence, except `class` values which are merged: ~~~mdc ::card{.featured} ```yaml [props] title: Featured Article author: Jane Doe tags: - markdown - documentation ``` This combines inline class `.featured` with YAML props :: ~~~ ### Use cases **Configuration-heavy components:** ~~~mdc ::data-table ```yaml [props] columns: - name: Name field: name sortable: true - name: Email field: email sortable: true options: striped: true pageSize: 10 ``` :: ~~~ **API documentation:** ~~~mdc ::api-endpoint ```yaml [props] method: POST path: /api/users parameters: - name: username type: string required: true - name: email type: string required: true response: status: 201 body: id: string username: string ``` :: ~~~ ## Data binding Props prefixed with `:` are JSON-parsed at render time. When the value isn't valid JSON, the renderer looks it up as a dot-path against an ambient **render context**, letting authors reference runtime data, frontmatter, meta, or the enclosing component's props without hardcoding them. ### Scope The render context exposes four namespaces: | Namespace | Source | | ------------- | ---------------------------------------------------- | | `frontmatter` | The document's YAML frontmatter | | `meta` | Plugin-populated metadata on the parsed tree | | `data` | Runtime values passed via the renderer's `data` prop | | `props` | The enclosing component's own props | ### Frontmatter Reference any value declared in the document's frontmatter: ```mdc --- theAnswer: 42 user: name: Ada --- ::question{:answer="frontmatter.theAnswer"} :: Hello, :badge{:label="frontmatter.user.name"} ``` ### Runtime data Pass values from your app via the renderer's `data` prop and reference them under the `data.` namespace: ::code-group ```vue [Vue] <Markdown :value="content" :data="{ user: { name: 'Ada' } }" /> ``` ```tsx [React] <Markdown value={content} data={{ user: { name: 'Ada' } }} /> ``` ```svelte [Svelte] <Markdown value={content} data={{ user: { name: 'Ada' } }} /> ``` ```typescript [Angular] <comark-markdown [value]="content" [data]="{ user: { name: 'Ada' } }" /> ``` :: ```mdc Welcome, :badge{:label="data.user.name"}! ``` ### Parent component props Nested components can read the enclosing component's resolved props through the `props.` namespace. This is useful when a child should mirror something declared once on its parent: ```mdc ::card{title="Hello" variant="primary"} :::badge{:color="props.variant" :text="props.title"} ::: :: ``` ### Resolution rules - If the `:prefixed` value is a valid JSON literal (for example `5`, `true`, `"foo"`, `{"a":1}`), it's used as-is. - Otherwise, the value is treated as a dot-path and resolved against `{ frontmatter, meta, data, props }`. - Unknown paths resolve to `undefined`: the prop is passed as `undefined` rather than the raw string. - Only props authored with the `:` prefix participate in data binding. Plain `prop="value"` attributes are always passed as literal strings. ::callout{color="info" icon="i-lucide-replace"} Need to interpolate a value directly into text rather than a prop? The [Binding plugin](https://comark.dev/plugins/built-in/binding) adds a `{{ path || default }}` inline shorthand that resolves against the same render context. :: ## Slots Block components support slots for passing structured content to components. ### Default slot Content placed directly inside a component goes to the default slot, no prefix needed: ```mdc ::alert{type="info"} This content goes to the default slot. :: ``` You can also write `#default` explicitly, which is useful when mixing it with named slots: ```mdc ::card #default This is the **default** slot content. #footer Footer content here. :: ``` ### Named slots ```mdc ::card #header ## Card Title #content This is the main content of the card #footer Footer text here :: ``` ### Combine with props You can use both YAML block props and named slots in the same component: ~~~mdc ::card{.featured} ```yaml [props] variant: elevated color: primary actions: - label: Read More url: /article - label: Share icon: share ``` #header ## Article Title *By Jane Doe* #content This is the main article content with **markdown** support. #footer Published on January 15, 2024 :: ~~~ ::callout{color="warning" icon="i-lucide-triangle-alert"} YAML block props must come immediately after the opening `::component` line, **before** any slot definitions. :: **Correct order:** ~~~mdc ::component{inline-attrs} ```yaml [props] yaml: props ``` #slot-name Slot content :: ~~~ **Incorrect order:** ~~~mdc ::component #slot-name Slot content ```yaml [props] yaml: props <!-- This won't work --> ``` :: ~~~ ## Nested Components can be nested within each other using additional colons: ```mdc ::outer-component Content in outer :::inner-component{variant="compact"} Content in inner ::: More content in outer :: ``` **Deep nesting:** ```mdc ::level-1 :::level-2 ::::level-3 Content :::: ::: :: ``` ::callout{color="info" icon="i-lucide-info"} Adding extra colons is not required but is a good practice to keep nesting visually consistent. The parser resolves nesting by matching opening and closing tags. :: This also works: ```mdc ::level-1 ::level-2 ::level-3 Content :: :: :: ``` --- - [Attributes](https://comark.dev/syntax/attributes) - [Components Plugin](https://comark.dev/plugins/defaults/components) # Attributes > Add custom classes, IDs, styles, and data attributes to native Markdown elements using the curly brace syntax. Comark allows adding custom attributes to native Markdown elements using `{...}` syntax after the element. Parsing is provided by the built-in [`attributes` plugin](https://comark.dev/plugins/defaults/attributes) (enabled by default). ## Element attributes ### Strong/bold ```mdc **bold text**{.highlight #important} **bold text**{data-value="custom"} **bold text**{bool} ``` ### Italic/emphasis ```mdc *italic text*{.emphasized} _italic text_{#custom-id} ``` ### Links ```mdc [Link text](url){target="_blank" rel="noopener"} [Link text](url){.button .primary} [External](https://example.com){target="_blank" .external-link} ``` ### Images ```mdc {.responsive width="800" height="600"} {.logo #site-logo} ``` ### Inline code ~~~mdc `code snippet`{.language-js} `variable`{data-type="string"} ~~~ ### Attribute types summary | Syntax | Output | Description | | -------------------------- | --------------------- | --------------------- | | `{bool}` | `:bool="true"` | Boolean attribute | | `{#my-id}` | `id="my-id"` | ID attribute | | `{.my-class}` | `class="my-class"` | Class attribute | | `{key="value"}` | `key="value"` | Key-value attribute | | `{:data='{"key": "val"}'}` | `data={"key": "val"}` | JSON object attribute | ## Span attributes Wrap inline text in a `<span>` element with custom attributes. This is useful for styling specific parts of text or adding metadata without creating custom components. ### Syntax ```mdc [text content]{attributes} ``` The text goes in square brackets `[...]` followed by attributes in curly braces `{...}`. ### Examples **Class:** ::code-group ```mdc [Syntax] This is [highlighted text]{.highlight} in a paragraph. ``` ```html [Output] <p>This is <span class="highlight">highlighted text</span> in a paragraph.</p> ``` :: **Multiple classes:** ::code-group ```mdc [Syntax] [Important]{.badge .primary} information here. ``` ```html [Output] <p><span class="badge primary">Important</span> information here.</p> ``` :: **ID:** ::code-group ```mdc [Syntax] Reference this [specific text]{#ref-1} later. ``` ```html [Output] <p>Reference this <span id="ref-1">specific text</span> later.</p> ``` :: **Inline styles:** ::code-group ```mdc [Syntax] [Blue text]{style="color: blue; font-weight: bold"} ``` ```html [Output] <p><span style="color: blue; font-weight: bold">Blue text</span></p> ``` :: **Data attributes:** ::code-group ```mdc [Syntax] [Earth]{data-planet="earth" data-type="terrestrial"} ``` ```html [Output] <p><span data-planet="earth" data-type="terrestrial">Earth</span></p> ``` :: **Combined attributes:** ::code-group ```mdc [Syntax] [Status: Active]{#status .badge .success data-state="active"} ``` ```html [Output] <p><span id="status" class="badge success" data-state="active">Status: Active</span></p> ``` :: ### Common use cases 1. **Styling with utility classes:** ```mdc [Warning]{.text-red-500 .font-bold}: System maintenance in progress. ``` 2. **Adding tooltips:** ```mdc Hover over [this text]{title="Additional information"} for more details. ``` 3. **Adding metadata for JavaScript:** ```mdc Click [here]{data-action="open-modal" data-target="login"} to sign in. ``` 4. **Accessibility attributes:** ```mdc [Important]{role="alert" aria-label="Critical notice"} security update available. ``` ### Nested Markdown Span syntax supports nested markdown formatting: ::code-group ```mdc [Syntax] [**Bold** and *italic* text]{.highlight} ``` ```html [Output] <p><span class="highlight"><strong>Bold</strong> and <em>italic</em> text</span></p> ``` :: ## Block attributes A trailing `{...}` on the last line of a block-level element attaches the attributes to that block. This works on paragraphs, headings, list items (bullet, ordered, and task list), and blockquote paragraphs. ### Paragraph ::code-group ```mdc [Syntax] A paragraph {attr="value"} ``` ```html [Output] <p attr="value">A paragraph</p> ``` :: ### Headings `{...}` after a heading attaches to that heading (alongside its auto-generated id when `headingIds` is enabled): ::code-group ```mdc [Syntax] # Heading 1 {.intro data-section="hero"} ## Heading 2 {attr="value"} ``` ```html [Output] <h1 id="heading-1" class="intro" data-section="hero">Heading 1</h1> <h2 id="heading-2" attr="value">Heading 2</h2> ``` :: A `{#id}` overrides the auto-generated id. When rendering back to markdown, the id is written out only if it differs from the auto-generated one, so custom ids survive a round trip: ::code-group ```mdc [Syntax] # Product Documentation {#prod-doc} ``` ```html [Output] <h1 id="prod-doc">Product Documentation</h1> ``` :: ### List items Bullet, ordered, and task-list items all accept trailing attributes: ::code-group ```mdc [Syntax] - a list item {attr="value"} - another list item {attr2="value2"} 1. List item {attr="value"} 2. List item {attr2="value2"} - [ ] Task list item {attr="value"} - [x] Task list item {attr2="value2"} ``` ```html [Output] <ul> <li attr="value">a list item</li> <li attr2="value2">another list item</li> </ul> <ol> <li attr="value">List item</li> <li attr2="value2">List item</li> </ol> <ul class="contains-task-list"> <li class="task-list-item" attr="value"><input ... /> Task list item</li> <li class="task-list-item" attr2="value2"><input ... /> Task list item</li> </ul> ``` :: ### Blockquote A single-line blockquote attaches the attributes to the blockquote element: ::code-group ```mdc [Syntax] > Blockquote {attr="value"} ``` ```html [Output] <blockquote attr="value">Blockquote</blockquote> ``` :: When a blockquote has multiple paragraphs, each paragraph's trailing `{...}` attaches to that paragraph: ::code-group ```mdc [Syntax] > Blockquote paragraph 1 {attr="value"} > > Blockquote paragraph 2 {attr2="value2"} ``` ```html [Output] <blockquote> <p attr="value">Blockquote paragraph 1</p> <p attr2="value2">Blockquote paragraph 2</p> </blockquote> ``` :: ### Span vs paragraph Whether the attributes attach to a span or to the surrounding paragraph depends on whether there is a space between the closing `]` and `{`: ::code-group ```mdc [Syntax] A paragraph [span] {attr="value"} A paragraph [span]{attr="value"} ``` ```html [Output] <p attr="value">A paragraph <span>span</span></p> <p>A paragraph <span attr="value">span</span></p> ``` :: ### Wrapping a list, table, blockquote, or code block For attributes that don't have a natural slot in the native syntax (lists, tables, multi-paragraph blockquotes, and fenced code blocks), use the matching `::tag` block component. When a `::ul`, `::ol`, `::table`, `::blockquote`, or `::pre` wraps a single same-tagged child, Comark folds them into one element, and the wrapper's attributes land on the actual list/table/blockquote/pre. ::code-group ~~~mdc [Syntax] ::ul{attr="value"} - item 1 - item 2 :: ::ol{attr="value"} 1. item 1 2. item 2 :: ::table{attr="value"} | col1 | col2 | | ---- | ---- | | a | b | :: ::blockquote{attr="value"} > Paragraph 1 > > Paragraph 2 :: ::pre{attr="value"} ```ts const variable = "value" ``` :: ~~~ ```html [Output] <ul attr="value"> <li>item 1</li> <li>item 2</li> </ul> <ol attr="value"> <li>item 1</li> <li>item 2</li> </ol> <table attr="value"> <thead><tr><th>col1</th><th>col2</th></tr></thead> <tbody><tr><td>a</td><td>b</td></tr></tbody> </table> <blockquote attr="value"> <p>Paragraph 1</p> <p>Paragraph 2</p> </blockquote> <pre data-language="ts" attr="value"><code class="language-ts">const variable = "value"</code></pre> ``` :: ::callout{color="info" icon="i-lucide-info"} Block attributes work on the standard Markdown elements above. For larger custom block content, use [Components](https://comark.dev/syntax/components) instead. :: --- - [Components](https://comark.dev/syntax/components) - [Attributes Plugin](https://comark.dev/plugins/defaults/attributes) # Frontmatter > Add a leading YAML block to declare document metadata that Comark parses into tree.frontmatter. Comark supports YAML frontmatter at the beginning of documents. Parsing is provided by the built-in [`frontmatter` plugin](https://comark.dev/plugins/defaults/frontmatter) (enabled by default). ## Syntax ```mdc --- title: My Document Title author: John Doe date: 2024-01-15 tags: - markdown - documentation depth: 3 searchDepth: 2 custom_field: custom value --- # Document Content Your markdown content here... ``` ### Rules - Must be at the **very beginning** of the document (no leading blank lines) - Enclosed by `---` delimiters - Body is parsed as YAML - Empty frontmatter (`---\n---` with no content) is ignored ## Parse result The `frontmatter` property is available on the parse result: ~~~ts import { parseMarkdown } from 'comark' const content = `--- title: My Article author: Jane Doe --- # Hello World ` const { frontmatter, nodes } = await parseMarkdown(content) /* frontmatter → { title: 'My Article', author: 'Jane Doe' } nodes → [ ['h1', { id: 'hello-world' }, 'Hello World'] ] */ ~~~ See [Document Model](https://comark.dev/getting-started/document-model#frontmatter) for how frontmatter sits on `MarkdownDocument`. ## Data binding Frontmatter values can be referenced in component props with the `:prefix` binding syntax: ```mdc --- theAnswer: 42 user: name: Ada --- ::question{:answer="frontmatter.theAnswer"} :: Hello, :badge{:label="frontmatter.user.name"} ``` Learn more in [Data Binding](https://comark.dev/syntax/components#data-binding). ## Disable Turn off all default plugins so the `---` block is treated as regular markdown: ```ts import { parseMarkdown } from 'comark' const result = await parseMarkdown(content, { registerDefaultPlugins: false, }) // result.frontmatter → {} ``` See the [frontmatter plugin](https://comark.dev/plugins/defaults/frontmatter) for registration and options. --- - [Frontmatter Plugin](https://comark.dev/plugins/defaults/frontmatter) - [Document Model](https://comark.dev/getting-started/document-model) # Markdown to HTML in JavaScript, No Framework > Convert Markdown to HTML strings in JavaScript without a framework, for server rendering, static sites, RSS feeds, and emails. The `@comark/html` package parses Markdown or renders an existing `MarkdownDocument` to an HTML string without a framework dependency. Use it for server-side rendering, static site generation, RSS feeds, and emails. ## Installation ::code-group ```bash [pnpm] pnpm add @comark/html ``` ```bash [npm] npm install @comark/html ``` ```bash [yarn] yarn add @comark/html ``` ```bash [bun] bun add @comark/html ``` :: ## `renderHtml()` The quickest way to parse markdown and get an HTML string in one call. ### Usage ::code-group ~~~typescript [Code] import { renderHtml } from '@comark/html' const html = await renderHtml(` # Getting Started This is a **bold** statement with a [link](https://example.com). - Item 1 - Item 2 `) ~~~ ```html [Output] <h1 id="getting-started">Getting Started</h1> <p>This is a <strong>bold</strong> statement with a <a href="https://example.com">link</a>.</p> <ul> <li>Item 1</li> <li>Item 2</li> </ul> ``` :: ### Options | Option | Type | Default | Description | | ------------------------------------------ | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------- | | [`plugins`](#render-options-plugins) | `ComarkPlugin[]` | `[]` | Array of plugins | | [`components`](#render-options-components) | `Record<string, fn>` | `{}` | Custom component renderers | | [`data`](#render-options-data) | `Record<string, any>` | `undefined` | Data passed to component renderers | | `autoClose` | `boolean` | `true` | Close incomplete Markdown and components before parsing | | `autoUnwrap` | `boolean` | `true` | Remove a single paragraph wrapper inside components | | `linkify` | `boolean` | `true` | Convert URL-like text into links | | `registerDefaultPlugins` | `boolean` | `true` | Register default plugins (`frontmatter`, `html`, `alert`, `task-list`, `components`, `attributes`) | | `unwrap` | `boolean \| string \| string[]` | `false` | Remove selected wrapper tags from the parsed document | `renderHtml()` accepts all [`ParserOptions`](https://comark.dev/reference/parse#options) in addition to the renderer options above. #### `plugins` See [ComarkPlugin](https://comark.dev/plugins) for available plugins. ```typescript import { renderHtml } from '@comark/html' import shiki from '@comark/html/plugins/shiki' import githubLight from '@shikijs/themes/github-light' import githubDark from '@shikijs/themes/github-dark' const html = await renderHtml('```js\nconsole.log("hi")\n```', { plugins: [ shiki({ themes: { light: githubLight, dark: githubDark } }) ], }) ``` #### `components` Map component names to async render functions. Each function receives the element as `[tag, attrs, ...children]` and a context with `render` to process nested content: ::code-group ~~~typescript [Code] import { renderHtml } from '@comark/html' const html = await renderHtml(` ::alert{type="warning"} This is a warning message! :: `, { components: { alert: async ([, attrs, ...children], { render }) => { return `<div class="alert alert-${attrs.type}" role="alert">${await render(children)}</div>` } } }) ~~~ ```html [Output] <div class="alert alert-warning" role="alert"><p>This is a warning message!</p></div> ``` :: #### `data` Pass external data to every component renderer via the context object: ::code-group ~~~typescript import { renderHtml } from '@comark/html' const html = await renderHtml(` ::header Welcome! :: `, { data: { siteName: 'My Blog' }, components: { header: async ([, , ...children], { render, data }) => { return `<header><h1>${data?.siteName}</h1>${await render(children)}</header>` } } }) ~~~ ```html [Output] <header><h1>My Blog</h1><p>Welcome!</p></header> ``` :: ### `createHtmlRenderer()` Creates a reusable parse+render function. The underlying parser is initialized once and reused on every call, which is more efficient when rendering many documents. #### Usage ```typescript import { createHtmlRenderer } from '@comark/html' import shiki from '@comark/html/plugins/shiki' const renderHtml = createHtmlRenderer({ plugins: [shiki()], }) // Reuse the same configured parser const html1 = await renderHtml('# Document 1\n\n...') const html2 = await renderHtml('# Document 2\n\n...') ``` #### Options Same as [`renderHtml()`](#renderhtml-options). --- ## `renderHtmlFromDocument()` Renders a pre-parsed `MarkdownDocument` directly, with no parsing step. Use it when you already have a document from a prior parse, build step, or API call. ### Integration Parse on the server and render in a separate step. No parser or plugin code needed at render time: ```typescript [server/api/content/[slug\\].ts] import { createMarkdownParser } from 'comark' import { readFile } from 'node:fs/promises' import { join } from 'node:path' const parse = createMarkdownParser() export default defineEventHandler(async (event) => { const slug = getRouterParam(event, 'slug') const markdown = await readFile(join('content', `${slug}.md`), 'utf-8') return parse(markdown) }) ``` Pass the pre-parsed document to `renderHtmlFromDocument`: ```typescript [render.ts] import { renderHtmlFromDocument } from '@comark/html' const document = await $fetch(`/api/content/${slug}`) const html = await renderHtmlFromDocument(document) ``` ### Options | Option | Type | Description | | ------------------------------------------ | --------------------- | ---------------------------------- | | [`components`](#render-options-components) | `Record<string, fn>` | Custom component renderers | | [`data`](#render-options-data) | `Record<string, any>` | Data passed to component renderers | --- ## Overriding HTML elements Pass native HTML tag names as keys in `components` to override how standard elements render: ```typescript import { createHtmlRenderer } from '@comark/html' const renderHtml = createHtmlRenderer({ components: { h1: async ([, attrs, ...children], { render }) => { const anchor = attrs.id ? `<a href="#${attrs.id}">#</a>` : '' return `<h1 id="${attrs.id}" class="heading">${anchor}${await render(children)}</h1>` }, a: async ([, attrs, ...children], { render }) => { const external = attrs.href?.startsWith('http') ? ' target="_blank" rel="noopener"' : '' return `<a href="${attrs.href}"${external}>${await render(children)}</a>` } } }) ``` --- ## TypeScript support ```typescript import type { ElementNode, Node } from 'comark' import { createHtmlRenderer } from '@comark/html' type RenderContext = { render: (nodes: Node[]) => Promise<string> data?: Record<string, any> } type ComponentRenderer = (element: ElementNode, ctx: RenderContext) => Promise<string> const components: Record<string, ComponentRenderer> = { alert: async ([, attrs, ...children], { render }) => { return `<div class="alert alert-${attrs.type}">${await render(children)}</div>` } } const renderHtml = createHtmlRenderer({ components }) ``` --- ## Use cases ### Static site generation ~~~typescript [build.ts] import { readFile, writeFile } from 'node:fs/promises' import { createHtmlRenderer } from '@comark/html' import shiki from '@comark/html/plugins/shiki' const renderHtml = createHtmlRenderer({ plugins: [shiki()] }) async function buildPage(filePath: string) { const source = await readFile(filePath, 'utf-8') const html = await renderHtml(source) await writeFile('out/index.html', ` <!DOCTYPE html> <html> <head><title>My Page ${html}