comark 0.0.1 → 0.1.1

package/dist/plugins/headings.d.ts

@@ -0,0 +1,48 @@
+import type { ComarkPlugin } from 'comark';
+export interface HeadingsOptions {
+    /**
+     * Tag to extract as title and set to `tree.meta.title`.
+     * @default 'h1'
+     */
+    titleTag?: string;
+    /**
+     * Tag to extract as description and set to `tree.meta.description`.
+     * Useful alternatives: `'blockquote'`
+     * @default 'p'
+     */
+    descriptionTag?: string;
+    /**
+     * Whether to remove the extracted nodes from the tree.
+     * @default true
+     */
+    remove?: boolean;
+}
+/**
+ * Extracts the title and description from the top of the document and sets
+ * them on `tree.meta.title` and `tree.meta.description`.
+ *
+ * The plugin scans the top-level nodes (ignoring `<hr>` and bare text nodes)
+ * and checks the first two content nodes in order:
+ *
+ * 1. If the first node matches `titleTag` (default `h1`), its text content is
+ *    written to `tree.meta.title`.
+ * 2. If the next content node matches `descriptionTag` (default `p`), its text
+ *    content is written to `tree.meta.description`. When no title was found,
+ *    this check starts from the very first content node.
+ *
+ * Both nodes are removed from the tree by default so they are not rendered
+ * twice. Set `remove: false` to keep them in place.
+ *
+ * @example
+ * ```ts
+ * // Default — h1 as title, first paragraph as description
+ * headings()
+ *
+ * // Use a blockquote as the description instead of a paragraph
+ * headings({ descriptionTag: 'blockquote' })
+ *
+ * // Extract metadata without removing the nodes from the tree
+ * headings({ remove: false })
+ * ```
+ */
+export default function headings(options?: HeadingsOptions): ComarkPlugin;

package/dist/plugins/headings.js

@@ -0,0 +1,85 @@
+function getTag(node) {
+    if (Array.isArray(node) && node.length >= 1) {
+        return node[0];
+    }
+    return null;
+}
+function getChildren(node) {
+    if (Array.isArray(node) && node.length > 2) {
+        return node.slice(2);
+    }
+    return [];
+}
+function flattenNodeText(node) {
+    if (typeof node === 'string') {
+        return node;
+    }
+    if (Array.isArray(node)) {
+        return getChildren(node).reduce((text, child) => {
+            return text + flattenNodeText(child);
+        }, '');
+    }
+    return '';
+}
+/**
+ * Extracts the title and description from the top of the document and sets
+ * them on `tree.meta.title` and `tree.meta.description`.
+ *
+ * The plugin scans the top-level nodes (ignoring `<hr>` and bare text nodes)
+ * and checks the first two content nodes in order:
+ *
+ * 1. If the first node matches `titleTag` (default `h1`), its text content is
+ *    written to `tree.meta.title`.
+ * 2. If the next content node matches `descriptionTag` (default `p`), its text
+ *    content is written to `tree.meta.description`. When no title was found,
+ *    this check starts from the very first content node.
+ *
+ * Both nodes are removed from the tree by default so they are not rendered
+ * twice. Set `remove: false` to keep them in place.
+ *
+ * @example
+ * ```ts
+ * // Default — h1 as title, first paragraph as description
+ * headings()
+ *
+ * // Use a blockquote as the description instead of a paragraph
+ * headings({ descriptionTag: 'blockquote' })
+ *
+ * // Extract metadata without removing the nodes from the tree
+ * headings({ remove: false })
+ * ```
+ */
+export default function headings(options = {}) {
+    const { titleTag = 'h1', descriptionTag = 'p', remove = true } = options;
+    return {
+        name: 'headings',
+        post(state) {
+            const nodes = state.tree.nodes;
+            // Top-level content nodes — skip raw text nodes and <hr>
+            const contentNodes = nodes.filter(node => Array.isArray(node) && getTag(node) !== 'hr');
+            let titleNodeIndex = -1;
+            let descriptionNodeIndex = -1;
+            const first = contentNodes[0];
+            if (first && getTag(first) === titleTag) {
+                titleNodeIndex = nodes.indexOf(first);
+                state.tree.meta.title = flattenNodeText(first);
+            }
+            // Description is the first content node after the (optional) title
+            const afterTitle = titleNodeIndex !== -1 ? contentNodes.slice(1) : contentNodes;
+            const second = afterTitle[0];
+            if (second && getTag(second) === descriptionTag) {
+                descriptionNodeIndex = nodes.indexOf(second);
+                state.tree.meta.description = flattenNodeText(second);
+            }
+            if (remove) {
+                // Remove in reverse order to preserve indices
+                const toRemove = [titleNodeIndex, descriptionNodeIndex]
+                    .filter(i => i !== -1)
+                    .sort((a, b) => b - a);
+                for (const i of toRemove) {
+                    nodes.splice(i, 1);
+                }
+            }
+        },
+    };
+}

package/dist/plugins/highlight.d.ts

@@ -0,0 +1,71 @@
+import type { LanguageRegistration } from 'shiki';
+import type { ComarkNode, ComarkTree, ComarkPlugin } from 'comark';
+import type { ShikiPrimitive, ThemeRegistration } from '@shikijs/primitive';
+import type { ShikiTransformer } from '@shikijs/types';
+export interface HighlightOptions {
+    /**
+     * Whether to use the default language definitions
+     * @default true
+     */
+    registerDefaultLanguages?: boolean;
+    /**
+     * Whether to use the default theme definitions
+     * @default true
+     */
+    registerDefaultThemes?: boolean;
+    /**
+     * Languages to preload. If not specified, languages will be loaded on demand.
+     * @default undefined (load on demand)
+     */
+    languages?: Array<LanguageRegistration | LanguageRegistration[]>;
+    /**
+     * Additional themes to preload
+     * @default { light: 'material-theme-lighter', dark: 'material-theme-palenight' }
+     */
+    themes?: {
+        light?: ThemeRegistration;
+        dark?: ThemeRegistration;
+    };
+    /**
+     * Transformers to apply to the code blocks
+     * @default undefined
+     */
+    transformers?: ShikiTransformer[];
+    /**
+     * Whether to add pre styles to the code blocks
+     * @default false
+     */
+    preStyles?: boolean;
+}
+export interface CodeBlockAttributes {
+    language?: string;
+    class?: string;
+    highlights?: number[];
+    meta?: string;
+}
+/**
+ * Get or create the Shiki highlighter instance
+ * Uses a singleton pattern to avoid creating multiple highlighters
+ */
+export declare function getHighlighter(options?: HighlightOptions): Promise<ShikiPrimitive>;
+/**
+ * Highlight code using Shiki with codeToTokens
+ * Returns comark nodes built from hast
+ */
+export declare function highlightCode(code: string, attrs: CodeBlockAttributes, options?: HighlightOptions): Promise<{
+    nodes: ComarkNode[];
+    language: string;
+    bgColor?: string;
+    fgColor?: string;
+}>;
+/**
+ * Apply syntax highlighting to all code blocks in a Comark tree
+ * Uses codeToTokens API with batched async operations
+ */
+export declare function highlightCodeBlocks(tree: ComarkTree, options?: HighlightOptions): Promise<ComarkTree>;
+/**
+ * Reset the highlighter instance
+ * Useful for testing or when you want to reconfigure
+ */
+export declare function resetHighlighter(): void;
+export default function highlight(options?: HighlightOptions): ComarkPlugin;

package/dist/plugins/highlight.js

@@ -0,0 +1,234 @@
+import { createShikiPrimitive } from '@shikijs/primitive';
+import { createJavaScriptRegexEngine } from 'shiki/engine/javascript';
+import { codeToHast } from 'shiki/core';
+let highlighter = null;
+let highlighterPromise = null;
+const loadedThemes = new Set();
+const loadedLanguages = new Set();
+/**
+ * Get or create the Shiki highlighter instance
+ * Uses a singleton pattern to avoid creating multiple highlighters
+ */
+export async function getHighlighter(options = {}) {
+    // If highlighter exists, load any new themes that aren't loaded yet
+    if (highlighter) {
+        const { themes, languages } = await registerDefaults(options);
+        await Promise.all(themes.map(theme => loadTheme(highlighter, theme)));
+        await Promise.all(languages.map(language => loadLanguage(highlighter, language)));
+        return highlighter;
+    }
+    if (highlighterPromise) {
+        return highlighterPromise;
+    }
+    try {
+        highlighterPromise = (async () => {
+            const { themes, languages } = await registerDefaults(options);
+            const hl = createShikiPrimitive({
+                themes: themes,
+                langs: languages,
+                langAlias: {
+                    md: 'mdc',
+                    markdown: 'mdc',
+                    comark: 'mdc',
+                },
+                engine: createJavaScriptRegexEngine({ forgiving: true }),
+            });
+            await Promise.all(themes.map(theme => loadTheme(hl, theme)));
+            await Promise.all(languages.map(language => loadLanguage(hl, language)));
+            return hl;
+        })();
+        highlighter = await highlighterPromise;
+        highlighterPromise = null;
+        return highlighter;
+    }
+    catch (error) {
+        console.error('Failed to create highlighter: make sure `shiki` is installed', error);
+        throw error;
+    }
+}
+async function registerDefaults(options) {
+    const themes = Object.values(options.themes || {});
+    const languages = options.languages || [];
+    const promises = [];
+    if (options.registerDefaultThemes !== false) {
+        promises.push(import('@shikijs/themes/material-theme-lighter').then(m => ({ type: 'theme', value: m.default })), import('@shikijs/themes/material-theme-palenight').then(m => ({ type: 'theme', value: m.default })));
+    }
+    if (options.registerDefaultLanguages !== false) {
+        promises.push(import('@shikijs/langs/vue').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/tsx').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/svelte').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/typescript').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/javascript').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/mdc').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/bash').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/json').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/yaml').then(m => ({ type: 'lang', value: m.default })), import('@shikijs/langs/astro').then(m => ({ type: 'lang', value: m.default })));
+    }
+    const results = await Promise.all(promises);
+    for (const result of results) {
+        if (result.type === 'theme')
+            themes.push(result.value);
+        else
+            languages.push(result.value);
+    }
+    return { themes, languages };
+}
+async function loadTheme(hl, theme) {
+    if (loadedThemes.has(theme.name || '')) {
+        return;
+    }
+    await hl.loadTheme(theme);
+    loadedThemes.add(theme.name || '');
+}
+async function loadLanguage(hl, language) {
+    if (loadedLanguages.has(Array.isArray(language) ? language.map(l => l.name || '').join(',') : language.name || '')) {
+        return;
+    }
+    await hl.loadLanguage(language);
+    loadedLanguages.add(Array.isArray(language) ? language.map(l => l.name || '').join(',') : language.name || '');
+}
+/**
+ * Highlight code using Shiki with codeToTokens
+ * Returns comark nodes built from hast
+ */
+export async function highlightCode(code, attrs, options = {}) {
+    // Extract language from attributes
+    const language = attrs?.language;
+    try {
+        const hl = await getHighlighter(options);
+        const { themes = { light: 'material-theme-lighter', dark: 'material-theme-palenight' } } = options;
+        const lightTheme = themes.light || themes.dark || 'material-theme-lighter';
+        const darkTheme = themes.dark || themes.light || 'material-theme-palenight';
+        // Use codeToTokens to get raw tokens
+        const result = await codeToHast(hl, code, {
+            lang: language,
+            transformers: options.transformers,
+            themes: {
+                light: lightTheme,
+                dark: lightTheme !== darkTheme ? darkTheme : undefined,
+            },
+            meta: {
+                __raw: attrs.meta,
+            },
+        });
+        const allTokens = result.children.map(hastToMinimarkNode);
+        return {
+            nodes: allTokens,
+            language,
+        };
+    }
+    catch (error) {
+        // If highlighting fails, return the original code
+        console.error('Shiki highlighting error:', error);
+        return {
+            nodes: [code],
+            language,
+        };
+    }
+    function hastToMinimarkNode(input) {
+        const props = input.properties || {};
+        if (input.type === 'comment')
+            return [null, {}, input.value];
+        if (input.type === 'text')
+            return input.value;
+        if (input.tag === 'code' && props?.className && props.className.length === 0)
+            delete props.className;
+        return [
+            input.tagName,
+            props,
+            ...(input.children || []).map(hastToMinimarkNode),
+        ];
+    }
+}
+/**
+ * Apply syntax highlighting to all code blocks in a Comark tree
+ * Uses codeToTokens API with batched async operations
+ */
+export async function highlightCodeBlocks(tree, options = {}) {
+    const codeBlocks = [];
+    const findCodeBlocks = (nodes, path) => {
+        for (let i = 0; i < nodes.length; i++) {
+            const node = nodes[i];
+            if (typeof node === 'string')
+                continue;
+            if (!Array.isArray(node) || node.length < 3)
+                continue;
+            if (node[0] === 'pre' && Array.isArray(node[2]) && node[2][0] === 'code') {
+                const codeContent = node[2][2];
+                if (typeof codeContent === 'string') {
+                    codeBlocks.push({ node, path: [...path, i] });
+                }
+            }
+            findCodeBlocks(node.slice(2), [...path, i]);
+        }
+    };
+    findCodeBlocks(tree.nodes, []);
+    if (codeBlocks.length === 0)
+        return tree;
+    const highlightedResults = await Promise.all(codeBlocks.map(({ node }) => {
+        return highlightCode(node[2][2], node[1], options);
+    }));
+    const newNodes = JSON.parse(JSON.stringify(tree.nodes));
+    for (let i = 0; i < codeBlocks.length; i++) {
+        const { node, path } = codeBlocks[i];
+        const result = highlightedResults[i];
+        const preNode = result.nodes[0];
+        const preNodeClasses = typeof preNode === 'string'
+            ? ['shiki', options.themes?.light?.name]
+            : (Array.isArray(preNode[1].class)
+                ? preNode[1].class
+                : String(preNode[1].class).split(' '));
+        const codeChildren = preNode[2].slice(2);
+        const children = typeof preNode === 'string' ? preNode : codeChildren.filter(element => element !== '\n');
+        const preAttrs = node[1];
+        const newPreAttrs = {
+            ...preAttrs,
+            class: [...preNodeClasses, options.themes?.dark?.name ? `dark:${options.themes?.dark?.name}` : ''].filter(Boolean).join(' '),
+            tabindex: '0',
+        };
+        if (options.preStyles) {
+            const lightTheme = options.themes?.light;
+            const darkTheme = options.themes?.dark;
+            const styles = [];
+            if (lightTheme?.colors?.['editor.background']) {
+                styles.push(`background-color:${lightTheme.colors['editor.background']}`);
+            }
+            if (lightTheme?.colors?.['editor.foreground']) {
+                styles.push(`color:${lightTheme.colors['editor.foreground']}`);
+            }
+            if (lightTheme?.name !== darkTheme?.name) {
+                if (darkTheme?.colors?.['editor.background']) {
+                    styles.push(`--shiki-dark-bg:${darkTheme.colors['editor.background']}`);
+                }
+                if (darkTheme?.colors?.['editor.foreground']) {
+                    styles.push(`--shiki-dark:${darkTheme.colors['editor.foreground']}`);
+                }
+            }
+            newPreAttrs.style = styles.join(';');
+        }
+        const codeEl = node[2];
+        const codeAttrs = codeEl[1] || {};
+        const newPreNode = ['pre', newPreAttrs, ['code', codeAttrs, ...children]];
+        if (path.length === 1) {
+            newNodes[path[0]] = newPreNode;
+        }
+        else {
+            let current = newNodes[path[0]];
+            for (let j = 1; j < path.length - 1; j++) {
+                current = current[path[j] + 2];
+            }
+            const childSlot = path[path.length - 1] + 2;
+            current[childSlot] = newPreNode;
+        }
+    }
+    return { ...tree, nodes: newNodes };
+}
+/**
+ * Reset the highlighter instance
+ * Useful for testing or when you want to reconfigure
+ */
+export function resetHighlighter() {
+    highlighter = null;
+    highlighterPromise = null;
+    loadedThemes.clear();
+}
+export default function highlight(options = {}) {
+    return {
+        name: 'highlight',
+        async post(state) {
+            state.tree = await highlightCodeBlocks(state.tree, options);
+        },
+    };
+}

package/dist/plugins/math.d.ts

@@ -0,0 +1,59 @@
+import type { ComarkPlugin } from 'comark';
+export interface MathConfig {
+    /**
+     * Throw on parse errors or return error message
+     * @default false
+     */
+    throwOnError?: boolean;
+    /**
+     * Additional katex options
+     */
+    options?: Record<string, unknown>;
+}
+/**
+ * Render LaTeX math expression to HTML using KaTeX
+ *
+ * @param code LaTeX math expression
+ * @param displayMode Whether to render in display mode
+ * @param config KaTeX configuration
+ * @returns HTML string
+ *
+ * @example
+ * ```ts
+ * const html = renderMath('E = mc^2', false)
+ * const display = renderMath('x^2', true)
+ * ```
+ */
+export declare function renderMath(code: string, displayMode: boolean, config?: MathConfig): string;
+/**
+ * Check if code is valid LaTeX math syntax
+ *
+ * @param code LaTeX math expression
+ * @returns true if valid, false otherwise
+ *
+ * @example
+ * ```ts
+ * validateMath('E = mc^2') // true
+ * validateMath('\\invalid') // false
+ * ```
+ */
+export declare function validateMath(code: string): boolean;
+/**
+ * Create math plugin for comark
+ *
+ * This plugin processes markdown-it tokens and converts math expressions
+ * with $ and $$ delimiters to HTML using KaTeX.
+ *
+ * @param config Math rendering configuration
+ *
+ * @example
+ * ```ts
+ * import { parse } from 'comark'
+ * import math from 'comark/plugins/math'
+ *
+ * const result = await parse('Inline $x^2$ and display $$E = mc^2$$', {
+ *   plugins: [math({ throwOnError: false })]
+ * })
+ * ```
+ */
+export default function math(config?: MathConfig): ComarkPlugin;