comark 0.2.1 → 0.3.0

package/README.md

@@ -48,7 +48,7 @@ const chatMessage = ...
 ```bash
 npm install @comark/react katex
 # or
-pnpm add @comark/react katex 
+pnpm add @comark/react katex
 ```
 
 ```tsx
@@ -97,8 +97,18 @@ const html = await render(chatMessage)
 ```
 
 
+## Agent skill
+
+Coding agents can install the Comark skill from the docs site:
+
+```bash
+npx skills add https://comark.dev
+```
+
+See [Installation](https://comark.dev/getting-started/installation) on comark.dev for details.
+
 ## License
 
 Made with ❤️
 
-Published under [MIT License](./LICENSE).
+Published under [MIT License](https://github.com/comarkdown/comark/blob/main/LICENSE).

package/dist/internal/frontmatter.d.ts

@@ -1,3 +1,4 @@
+import type { DumpOptions } from 'js-yaml';
 /**
  * Parse frontmatter from content
  * @param content - The content to parse
@@ -13,4 +14,4 @@ export declare function parseFrontmatter(content: string): {
  * @param content - The content to render
  * @returns The rendered content
  */
-export declare function renderFrontmatter(data: Record<string, any> | undefined | null, content?: string): string;
+export declare function renderFrontmatter(data: Record<string, any> | undefined | null, content?: string, yamlOptions?: DumpOptions): string;

package/dist/internal/frontmatter.js

@@ -31,11 +31,11 @@ export function parseFrontmatter(content) {
  * @param content - The content to render
  * @returns The rendered content
  */
-export function renderFrontmatter(data, content) {
+export function renderFrontmatter(data, content, yamlOptions) {
     if (!data || Object.keys(data).length === 0) {
         return (content?.trim() || '');
     }
-    const fm = stringifyYaml(data).trim();
+    const fm = stringifyYaml(data, yamlOptions).trim();
     if (content) {
         return FRONTMATTER_DELIMITER_DEFAULT + LF + fm + LF + FRONTMATTER_DELIMITER_DEFAULT + LF + LF + content.trim();
     }

package/dist/internal/parse/auto-close/index.js

@@ -196,8 +196,55 @@ function closeInlineMarkersLinear(line) {
     const doubleAsteriskPositions = [];
     const doubleUnderscorePositions = [];
     // Single-pass scan through the line - O(n)
+    // Skip markers inside attribute scopes {...} and link text [...] / link URL (...)
+    let inAttributes = 0;
+    let inLinkText = 0;
+    let inLinkUrl = 0;
     for (let i = 0; i < len; i++) {
+        const prevCh = i > 0 ? line[i - 1] : '';
         const ch = line[i];
+        if (ch === '{' && prevCh !== ' ') {
+            inAttributes++;
+            continue;
+        }
+        if (ch === '}') {
+            if (inAttributes > 0)
+                inAttributes--;
+            continue;
+        }
+        if (inAttributes > 0)
+            continue;
+        if (ch === '[') {
+            bracketBalance++;
+            lastBracketPos = i;
+            inLinkText++;
+            continue;
+        }
+        if (ch === ']') {
+            bracketBalance--;
+            lastBracketPos = i;
+            if (inLinkText > 0)
+                inLinkText--;
+            continue;
+        }
+        if (ch === '(') {
+            if (lastBracketPos >= 0 && i > lastBracketPos) {
+                parenBalance++;
+                if (prevCh === ']')
+                    inLinkUrl++;
+            }
+            continue;
+        }
+        if (ch === ')') {
+            if (lastBracketPos >= 0 && i > lastBracketPos) {
+                parenBalance--;
+                if (inLinkUrl > 0)
+                    inLinkUrl--;
+            }
+            continue;
+        }
+        if (inLinkText > 0 || inLinkUrl > 0)
+            continue;
         if (ch === '*') {
             asteriskCount++;
             // Track ** positions (not part of ***)
@@ -209,10 +256,16 @@ function closeInlineMarkersLinear(line) {
             }
         }
         else if (ch === '_') {
-            underscoreCount++;
-            // Track __ positions (for bold)
-            if (i + 1 < len && line[i + 1] === '_') {
-                doubleUnderscorePositions.push(i);
+            // Skip intra-word underscores (not emphasis delimiters per CommonMark)
+            const nextCh = i + 1 < len ? line[i + 1] : '';
+            const prevIsWord = (prevCh >= 'a' && prevCh <= 'z') || (prevCh >= 'A' && prevCh <= 'Z') || (prevCh >= '0' && prevCh <= '9');
+            const nextIsWord = (nextCh >= 'a' && nextCh <= 'z') || (nextCh >= 'A' && nextCh <= 'Z') || (nextCh >= '0' && nextCh <= '9');
+            if (!(prevIsWord && nextIsWord)) {
+                underscoreCount++;
+                // Track __ positions (for bold)
+                if (nextCh === '_') {
+                    doubleUnderscorePositions.push(i);
+                }
             }
         }
         else if (ch === '~') {
@@ -221,7 +274,7 @@ function closeInlineMarkersLinear(line) {
         else if (ch === '`') {
             backtickCount++;
         }
-        else if (ch === '$') {
+        else if (ch === '$' && prevCh !== '\\') {
             // Count $$ pairs for block/display math
             if (i + 1 < len && line[i + 1] === '$') {
                 dollarPairCount++;
@@ -232,24 +285,6 @@ function closeInlineMarkersLinear(line) {
                 dollarCount++; // Single $ for inline math
             }
         }
-        else if (ch === '[') {
-            bracketBalance++;
-            lastBracketPos = i;
-        }
-        else if (ch === ']') {
-            bracketBalance--;
-            lastBracketPos = i;
-        }
-        else if (ch === '(') {
-            if (lastBracketPos >= 0 && i > lastBracketPos) {
-                parenBalance++;
-            }
-        }
-        else if (ch === ')') {
-            if (lastBracketPos >= 0 && i > lastBracketPos) {
-                parenBalance--;
-            }
-        }
     }
     // Check for complete ** pairs in O(1) - pairs are matched left to right
     const hasCompleteBoldPair = doubleAsteriskPositions.length >= 2;

package/dist/internal/parse/token-processor.js

@@ -26,6 +26,7 @@ const INLINE_TAG_MAP = {
 export function marmdownItTokensToComarkTree(tokens, options = { startLine: 0, preservePositions: false }) {
     const state = {
         headingSlugCounts: new Map(),
+        headingStack: [],
         preservePositions: options.preservePositions,
     };
     const nodes = [];
@@ -302,14 +303,14 @@ function processBlockToken(tokens, startIndex, insideNestedContext = false, stat
         return { node: pre, nextIndex: startIndex + 1 };
     }
     if (token.type === 'heading_open') {
-        const level = token.tag.replace('h', '');
+        const level = Number.parseInt(token.tag.replace('h', ''), 10);
         const headingTag = `h${level}`;
         // Process heading children with inHeading flag for Comark component handling
         const children = processBlockChildren(tokens, startIndex + 1, 'heading_close', true, true, insideNestedContext, state);
         if (children.nodes.length > 0) {
             // Always generate ID for all headings, no exceptions
             const textContent = extractTextContent(children.nodes);
-            const headingId = uniqueSlug(slugify(textContent), state);
+            const headingId = uniqueSlug(slugify(textContent), level, state);
             // Always attach ID to the heading element itself
             return { node: [headingTag, { id: headingId }, ...children.nodes], nextIndex: children.nextIndex + 1 };
         }
@@ -522,9 +523,23 @@ function slugify(text) {
 /**
  * Return a unique slug by appending a numeric suffix for duplicates
  */
-function uniqueSlug(slug, state) {
+function uniqueSlug(slug, level, state) {
     if (!state)
         return slug;
+    // Build hierarchical ID: pop headings at same or deeper level, then prefix with parent's ID
+    // Pop headings at same level or deeper
+    while (state.headingStack.length > 0 && state.headingStack[state.headingStack.length - 1].level >= level) {
+        state.headingStack.pop();
+    }
+    // Use parent's full ID as prefix (h1 doesn't prefix children)
+    if (state.headingStack.length > 0) {
+        const parent = state.headingStack[state.headingStack.length - 1];
+        if (parent.level >= 2) {
+            slug = parent.id + '-' + slug;
+        }
+    }
+    // Push onto stack for child headings to reference
+    state.headingStack.push({ level, id: slug });
     const count = state.headingSlugCounts.get(slug) ?? 0;
     state.headingSlugCounts.set(slug, count + 1);
     return count === 0 ? slug : `${slug}-${count}`;

package/dist/internal/stringify/attributes.d.ts

@@ -1,3 +1,39 @@
+import type { NodeRenderData } from '../../types.ts';
+export interface ResolveAttributesOptions {
+    /**
+     * When true, every `:prefixed` string value is JSON-parsed first and the
+     * `:` prefix is always stripped. Non-JSON strings fall back to a dot-path
+     * lookup in `renderData`; unresolved paths yield `undefined`.
+     *
+     * This matches the Vue/React/Svelte renderer semantics, which always
+     * normalize bindings into real JS values suitable for typed component props.
+     *
+     * When false (default) only dot-path lookups are applied — literals and
+     * unresolved paths are preserved verbatim so string-based serializers
+     * (like HTML attribute emitters) can apply their own `:prefix` handling.
+     */
+    parseJson?: boolean;
+}
+/**
+ * Resolve `:prefixed` attributes against the render context.
+ *
+ * Default behavior: a `:prefixed` string value that matches a dot-path in
+ * `{ frontmatter, meta, data, props }` is replaced with the resolved value
+ * (and the `:` prefix is stripped). Anything that doesn't resolve — literals
+ * like `"5"` / `"true"`, unknown paths, or already-parsed object values — is
+ * left untouched and keeps its `:` prefix.
+ *
+ * With `parseJson: true`, every `:prefixed` string is JSON-parsed first and
+ * the `:` prefix is always stripped, falling back to the dot-path lookup.
+ * The `$` metadata key is never forwarded.
+ */
+export declare function resolveAttributes(attrs: Record<string, unknown>, renderData: NodeRenderData, options?: ResolveAttributesOptions): Record<string, unknown>;
+/**
+ * Read a named attribute, preferring its `:prefixed` binding (resolved against
+ * `renderData`) over the literal `key`. Falls back to the raw value when the
+ * binding doesn't resolve.
+ */
+export declare function resolveAttribute(attrs: Record<string, unknown>, renderData: NodeRenderData, key: string): unknown;
 /**
  * Convert attributes to a string of Comark attributes
  *
@@ -18,4 +54,4 @@ export declare function htmlAttributes(attributes: Record<string, unknown>): str
  * @param attributes - The attributes to stringify
  * @returns The stringified attributes
  */
-export declare function comarkYamlAttributes(attributes: Record<string, unknown>): string;
+export declare function comarkYamlAttributes(attributes: Record<string, unknown>, style?: 'frontmatter' | 'codeblock'): string;

package/dist/internal/stringify/attributes.js

@@ -1,4 +1,72 @@
 import { stringifyYaml } from "../yaml.js";
+import { get } from "../../utils/index.js";
+/**
+ * Resolve `:prefixed` attributes against the render context.
+ *
+ * Default behavior: a `:prefixed` string value that matches a dot-path in
+ * `{ frontmatter, meta, data, props }` is replaced with the resolved value
+ * (and the `:` prefix is stripped). Anything that doesn't resolve — literals
+ * like `"5"` / `"true"`, unknown paths, or already-parsed object values — is
+ * left untouched and keeps its `:` prefix.
+ *
+ * With `parseJson: true`, every `:prefixed` string is JSON-parsed first and
+ * the `:` prefix is always stripped, falling back to the dot-path lookup.
+ * The `$` metadata key is never forwarded.
+ */
+export function resolveAttributes(attrs, renderData, options = {}) {
+    const result = {};
+    for (const key in attrs) {
+        if (key === '$')
+            continue;
+        const value = attrs[key];
+        const isBinding = key.charCodeAt(0) === 58; /* ':' */
+        if (options.parseJson && isBinding) {
+            // Framework mode: always strip `:` and hand components real JS values.
+            if (typeof value === 'string') {
+                try {
+                    result[key.slice(1)] = JSON.parse(value);
+                    continue;
+                }
+                catch {
+                    // not JSON — fall through to dot-path lookup
+                }
+                result[key.slice(1)] = get(renderData, value);
+                continue;
+            }
+            // Non-string binding value (e.g. an object literal the parser already
+            // decoded) — pass through with the prefix stripped.
+            result[key.slice(1)] = value;
+            continue;
+        }
+        if (isBinding && typeof value === 'string') {
+            const resolved = get(renderData, value);
+            if (resolved !== undefined) {
+                result[key.slice(1)] = resolved;
+                continue;
+            }
+        }
+        result[key] = value;
+    }
+    return result;
+}
+/**
+ * Read a named attribute, preferring its `:prefixed` binding (resolved against
+ * `renderData`) over the literal `key`. Falls back to the raw value when the
+ * binding doesn't resolve.
+ */
+export function resolveAttribute(attrs, renderData, key) {
+    const bindKey = `:${key}`;
+    if (bindKey in attrs) {
+        const value = attrs[bindKey];
+        if (typeof value === 'string') {
+            const resolved = get(renderData, value);
+            if (resolved !== undefined)
+                return resolved;
+        }
+        return value;
+    }
+    return attrs[key];
+}
 /**
  * Convert attributes to a string of Comark attributes
  *
@@ -32,22 +100,33 @@ export function comarkAttributes(attributes) {
  * @returns The stringified attributes
  */
 export function htmlAttributes(attributes) {
-    return Object.entries(attributes)
-        .map(([key, value]) => {
+    const parts = [];
+    for (const [key, value] of Object.entries(attributes)) {
         if (key.startsWith(':')) {
             if (value === 'true') {
-                return key.slice(1);
+                parts.push(key.slice(1));
+                continue;
+            }
+            if (typeof value === 'object' && value !== null) {
+                parts.push(`${key.slice(1)}="${JSON.stringify(value).replace(/"/g, '\\"')}"`);
+                continue;
             }
-            return `${key.slice(1)}="${value}"`;
+            parts.push(`${key.slice(1)}="${value}"`);
+            continue;
         }
-        if (value === 'true')
-            return key;
+        if (value === true || value === 'true') {
+            parts.push(key);
+            continue;
+        }
+        if (value === false || value === null || value === undefined)
+            continue;
         if (typeof value === 'object') {
-            return `${key}="${JSON.stringify(value).replace(/"/g, '\\"')}"`;
+            parts.push(`${key}="${JSON.stringify(value).replace(/"/g, '\\"')}"`);
+            continue;
         }
-        return `${key}="${value}"`;
-    })
-        .join(' ');
+        parts.push(`${key}="${value}"`);
+    }
+    return parts.join(' ');
 }
 /**
  * Convert attributes to a string of YAML attributes
@@ -55,7 +134,7 @@ export function htmlAttributes(attributes) {
  * @param attributes - The attributes to stringify
  * @returns The stringified attributes
  */
-export function comarkYamlAttributes(attributes) {
+export function comarkYamlAttributes(attributes, style = 'codeblock') {
     // Normalize boolean attributes to remove the colon prefix
     const normalized = Object.fromEntries(Object.entries(attributes).map(([key, value]) => {
         if (key.startsWith(':') && (value === 'true' || value === 'false')) {
@@ -63,5 +142,10 @@ export function comarkYamlAttributes(attributes) {
         }
         return [key, value];
     }));
-    return `---\n${stringifyYaml(normalized).trim()}\n---`;
+    const yamlContent = stringifyYaml(normalized).trim();
+    if (style === 'frontmatter') {
+        return `---\n${yamlContent}\n---`;
+    }
+    const fence = yamlContent.includes('```') ? '~~~' : '```';
+    return `${fence}yaml [props]\n${yamlContent}\n${fence}`;
 }

package/dist/internal/stringify/handlers/a.js

@@ -7,5 +7,8 @@ export async function a(node, state) {
         ? comarkAttributes(rest)
         : '';
     const content = await state.flow(node, state);
+    if (content === href && !attrsString) {
+        return `<${href}>`;
+    }
     return `[${content}](${href})${attrsString}`;
 }

package/dist/internal/stringify/handlers/code.js

@@ -1,5 +1,5 @@
 import { comarkAttributes } from "../attributes.js";
-import { textContent } from 'comark/utils';
+import { textContent } from "../../../utils/index.js";
 export function code(node, _state) {
     const [_, attrs] = node;
     const attrsString = Object.keys(attrs).length > 0

package/dist/internal/stringify/handlers/del.js

@@ -1,4 +1,4 @@
-import { textContent } from 'comark/utils';
+import { textContent } from "../../../utils/index.js";
 export function del(node, _) {
     return `~~${textContent(node)}~~`;
 }

package/dist/internal/stringify/handlers/html.js

@@ -6,7 +6,18 @@ const inlineTags = new Set(['strong', 'em', 'code', 'a', 'br', 'span', 'img']);
 const blockTags = new Set(['p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'li', 'ul', 'ol', 'blockquote', 'hr', 'table', 'td', 'th']);
 export async function html(node, state, parent) {
     const [tag, attr, ...children] = node;
-    const { $ = {}, ...attributes } = attr;
+    const { $ = {}, ...rawAttributes } = attr;
+    // In text/html mode, `one()` has already resolved this element's `:prefix`
+    // bindings against the parent's render context and stored the result in
+    // `state.renderData.props` — but only when the element has its own attrs.
+    // If it doesn't, `state.renderData.props` still holds the enclosing scope
+    // (so that `{{ props.* }}` in nested children keeps working), so we fall
+    // back to the raw (empty) attrs to avoid leaking parent props onto native
+    // wrappers like `<p>` or `<ul>`.
+    const rawHasAttrs = Object.keys(rawAttributes).length > 0;
+    const attributes = state.context.html
+        ? (rawHasAttrs ? state.renderData.props : rawAttributes)
+        : rawAttributes;
     const hasOnlyTextChildren = children.every(child => typeof child === 'string' || inlineTags.has(String(child?.[0])));
     const hasTextSibling = children.some(child => typeof child === 'string');
     const isBlock = textBlocks.has(String(tag));

package/dist/internal/stringify/handlers/img.js

@@ -1,7 +1,7 @@
 import { comarkAttributes } from "../attributes.js";
 export function img(node, _state) {
     const [_, attrs] = node;
-    const { title, src, alt, ...rest } = attrs;
+    const { title, src, alt = '', ...rest } = attrs;
     const attrsString = Object.keys(rest).length > 0
         ? comarkAttributes(rest)
         : '';

package/dist/internal/stringify/handlers/li.js

@@ -1,3 +1,7 @@
+import { indent } from "../indent.js";
+// Block elements that need explicit indentation in list items.
+// Note: ol/ul are handled by their own handlers which manage indentation via listIndent context.
+const blockElements = new Set(['pre', 'blockquote', 'table']);
 export async function li(node, state) {
     const children = node.slice(2);
     const order = state.context.order;
@@ -10,9 +14,18 @@ export async function li(node, state) {
         const input = children.shift();
         prefix += input[1].checked || input[1][':checked'] ? '[x] ' : '[ ] ';
     }
+    const prefixWidth = prefix.length;
     let result = '';
     for (const child of children) {
-        result += await state.one(child, state, node);
+        const rendered = await state.one(child, state, node);
+        if (Array.isArray(child) && blockElements.has(child[0])) {
+            // Block-level child: put on its own line and indent to align with list prefix
+            const indented = indent(rendered, { width: prefixWidth });
+            result = result.trimEnd() + '\n' + indented.trimEnd() + '\n';
+        }
+        else {
+            result += rendered;
+        }
     }
     result = result.trim();
     if (!order) {

package/dist/internal/stringify/handlers/math.js

@@ -1,4 +1,4 @@
-import { textContent } from 'comark/utils';
+import { textContent } from "../../../utils/index.js";
 export function math(node, state, parent) {
     const content = textContent(node);
     if (parent?.some((child, index) => index > 1 && typeof child === 'string')) {

package/dist/internal/stringify/handlers/mdc.js

@@ -37,7 +37,7 @@ export async function mdc(node, state, parent) {
         const maxInlineAttributes = state.context.maxInlineAttributes ?? 3;
         const useYaml = hasObjectAttributes || maxInlineAttributes === 0 || attributeEntries.length > maxInlineAttributes;
         if (useYaml) {
-            const yamlAttrs = comarkYamlAttributes(attributes);
+            const yamlAttrs = comarkYamlAttributes(attributes, state.context.blockAttributesStyle);
             result = `${fence}${tag}\n${yamlAttrs}${content ? `\n${content}` : ''}\n${fence}` + state.context.blockSeparator;
         }
         else {

package/dist/internal/stringify/handlers/ol.js

@@ -1,14 +1,14 @@
 import { indent } from "../indent.js";
 export async function ol(node, state) {
     const children = node.slice(2);
-    const revert = state.applyContext({ list: true, order: 1 });
+    const revert = state.applyContext({ list: true, order: 1, listIndent: 3 });
     let result = '';
     for (const child of children) {
         result += await state.one(child, state);
     }
     result = result.trim();
     if (revert.list) {
-        result = '\n' + indent(result);
+        result = '\n' + indent(result, { width: revert.listIndent || 2 });
     }
     else {
         result = result + state.context.blockSeparator;

package/dist/internal/stringify/handlers/pre.js

@@ -1,4 +1,4 @@
-import { textContent } from 'comark/utils';
+import { textContent } from "../../../utils/index.js";
 export function pre(node, state) {
     const [_, attributes, ...children] = node;
     const codeClasses = children[0]?.[1]?.class;

package/dist/internal/stringify/handlers/template.js

@@ -1,7 +1,7 @@
 // slot template
 export async function template(node, state, parent) {
     const [_, attrs] = node;
-    const content = (await state.flow(node, state)).trim();
+    const content = (await state.flow(node, state)).trimEnd();
     // Omit #default marker if this is the only slot
     if (attrs.name === 'default') {
         const siblings = parent ? parent.slice(2) : [];

package/dist/internal/stringify/handlers/ul.js

@@ -1,14 +1,14 @@
 import { indent } from "../indent.js";
 export async function ul(node, state) {
     const children = node.slice(2);
-    const revert = state.applyContext({ list: true, order: false });
+    const revert = state.applyContext({ list: true, order: false, listIndent: 2 });
     let result = '';
     for (const child of children) {
         result += await state.one(child, state);
     }
     result = result.trim();
     if (revert.list) {
-        result = '\n' + indent(result);
+        result = '\n' + indent(result, { width: revert.listIndent || 2 });
     }
     else {
         result = result + state.context.blockSeparator;

package/dist/internal/stringify/indent.d.ts

@@ -1,4 +1,5 @@
-export declare function indent(text: string, { ignoreFirstLine, level }?: {
+export declare function indent(text: string, { ignoreFirstLine, level, width }?: {
     ignoreFirstLine?: boolean;
     level?: number;
+    width?: number;
 }): string;

package/dist/internal/stringify/indent.js

@@ -1,8 +1,9 @@
-export function indent(text, { ignoreFirstLine = false, level = 1 } = {}) {
+export function indent(text, { ignoreFirstLine = false, level = 1, width } = {}) {
+    const pad = width ? ' '.repeat(width) : '  '.repeat(level);
     return text.split('\n').map((line, index) => {
         if (ignoreFirstLine && index === 0) {
             return line;
         }
-        return line ? '  '.repeat(level) + line : line;
+        return line ? pad + line : line;
     }).join('\n');
 }

package/dist/internal/stringify/state.d.ts

@@ -1,5 +1,5 @@
-import type { State, Context } from 'comark/render';
-import type { ComarkElement, ComarkNode } from 'comark';
+import type { State } from 'comark/render';
+import type { ComarkElement, ComarkNode, CreateContext } from 'comark';
 /**
  * Render a single node
  * @param node - The node to render
@@ -9,5 +9,5 @@ import type { ComarkElement, ComarkNode } from 'comark';
  */
 export declare function one(node: ComarkNode, state: State, parent?: ComarkElement): Promise<string>;
 export declare function flow(node: ComarkElement, state: State, parent?: ComarkElement): Promise<string>;
-export declare function createState(ctx?: Partial<Context>): State;
+export declare function createState(ctx?: Partial<CreateContext>): State;
 export declare const state: State;