@classic-homes/theme-docs 0.0.2

package/dist/lib/parser/extensions.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Marked Extensions for Enhanced Markdown Features
+ *
+ * Provides support for:
+ * - Admonitions/Callouts (note, tip, warning, important, caution)
+ * - Footnotes
+ * - Definition Lists
+ * - Mermaid diagram placeholders (rendered client-side)
+ */
+import type { MarkedExtension } from 'marked';
+/**
+ * Admonition types and their corresponding icons/classes
+ */
+export declare const ADMONITION_TYPES: readonly ["note", "tip", "warning", "important", "caution"];
+export type AdmonitionType = (typeof ADMONITION_TYPES)[number];
+/**
+ * Admonition extension for marked
+ *
+ * Syntax:
+ * :::note
+ * This is a note
+ * :::
+ *
+ * :::warning Title Here
+ * This is a warning with a custom title
+ * :::
+ */
+export declare function admonitionExtension(): MarkedExtension;
+/**
+ * Reset footnote store (call before parsing a new document)
+ */
+export declare function resetFootnoteStore(): void;
+/**
+ * Footnotes extension for marked
+ *
+ * Syntax:
+ * Here is some text[^1] with a footnote.
+ *
+ * [^1]: This is the footnote content.
+ */
+export declare function footnoteExtension(): MarkedExtension;
+/**
+ * Render collected footnotes as a section
+ * Call this after parsing to get the footnotes HTML
+ */
+export declare function renderFootnotes(): string;
+/**
+ * Definition list extension for marked
+ *
+ * Syntax:
+ * Term 1
+ * : Definition for term 1
+ *
+ * Term 2
+ * : Definition for term 2
+ * : Another definition for term 2
+ */
+export declare function definitionListExtension(): MarkedExtension;
+/**
+ * Mermaid code block extension for marked
+ *
+ * Converts mermaid code blocks to placeholder divs that can be
+ * rendered client-side by the Mermaid library.
+ *
+ * Syntax:
+ * ```mermaid
+ * graph TD
+ *   A --> B
+ * ```
+ */
+export declare function mermaidExtension(): MarkedExtension;
+/**
+ * Get all markdown extensions
+ */
+export declare function getAllExtensions(): MarkedExtension[];

package/dist/lib/parser/extensions.js

@@ -0,0 +1,311 @@
+/**
+ * Marked Extensions for Enhanced Markdown Features
+ *
+ * Provides support for:
+ * - Admonitions/Callouts (note, tip, warning, important, caution)
+ * - Footnotes
+ * - Definition Lists
+ * - Mermaid diagram placeholders (rendered client-side)
+ */
+/**
+ * Admonition types and their corresponding icons/classes
+ */
+export const ADMONITION_TYPES = ['note', 'tip', 'warning', 'important', 'caution'];
+/**
+ * Admonition extension for marked
+ *
+ * Syntax:
+ * :::note
+ * This is a note
+ * :::
+ *
+ * :::warning Title Here
+ * This is a warning with a custom title
+ * :::
+ */
+export function admonitionExtension() {
+    return {
+        extensions: [
+            {
+                name: 'admonition',
+                level: 'block',
+                start(src) {
+                    return src.match(/^:::/)?.index;
+                },
+                tokenizer(src) {
+                    // Match :::type optional-title\ncontent\n:::
+                    const match = src.match(/^:::(note|tip|warning|important|caution)(?:\s+([^\n]*))?\n([\s\S]*?)\n:::/);
+                    if (match) {
+                        const token = {
+                            type: 'admonition',
+                            raw: match[0],
+                            admonitionType: match[1],
+                            title: match[2]?.trim() || match[1].charAt(0).toUpperCase() + match[1].slice(1),
+                            content: match[3].trim(),
+                            tokens: [],
+                        };
+                        // Parse the inner content as markdown
+                        this.lexer.blockTokens(token.content, token.tokens);
+                        return token;
+                    }
+                    return undefined;
+                },
+                renderer(token) {
+                    const innerHtml = this.parser.parse(token.tokens ?? []);
+                    const iconMap = {
+                        note: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="10"/><line x1="12" y1="16" x2="12" y2="12"/><line x1="12" y1="8" x2="12.01" y2="8"/></svg>`,
+                        tip: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M9.663 17h4.673M12 3v1m6.364 1.636l-.707.707M21 12h-1M4 12H3m3.343-5.657l-.707-.707m2.828 9.9a5 5 0 117.072 0l-.548.547A3.374 3.374 0 0014 18.469V19a2 2 0 11-4 0v-.531c0-.895-.356-1.754-.988-2.386l-.548-.547z"/></svg>`,
+                        warning: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>`,
+                        important: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z"/><path d="M12 8v4"/><path d="M12 16h.01"/></svg>`,
+                        caution: `<svg class="admonition-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M7.86 2h8.28L22 7.86v8.28L16.14 22H7.86L2 16.14V7.86L7.86 2z"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>`,
+                    };
+                    return `<div class="admonition admonition-${token.admonitionType}">
+  <div class="admonition-heading">
+    ${iconMap[token.admonitionType]}
+    <span class="admonition-title">${token.title}</span>
+  </div>
+  <div class="admonition-content">${innerHtml}</div>
+</div>`;
+                },
+            },
+        ],
+    };
+}
+let footnoteStore = {
+    definitions: new Map(),
+    references: new Set(),
+};
+/**
+ * Reset footnote store (call before parsing a new document)
+ */
+export function resetFootnoteStore() {
+    footnoteStore = {
+        definitions: new Map(),
+        references: new Set(),
+    };
+}
+/**
+ * Footnotes extension for marked
+ *
+ * Syntax:
+ * Here is some text[^1] with a footnote.
+ *
+ * [^1]: This is the footnote content.
+ */
+export function footnoteExtension() {
+    return {
+        extensions: [
+            // Footnote definition: [^id]: content
+            {
+                name: 'footnoteDefinition',
+                level: 'block',
+                start(src) {
+                    return src.match(/^\[\^[^\]]+\]:/)?.index;
+                },
+                tokenizer(src) {
+                    // Match [^id]: content (can span multiple lines if indented)
+                    const match = src.match(/^\[\^([^\]]+)\]:\s*([\s\S]*?)(?=\n\[\^|\n\n|\n(?=[^\s])|\s*$)/);
+                    if (match) {
+                        const id = match[1];
+                        const content = match[2].trim();
+                        const token = {
+                            type: 'footnoteDefinition',
+                            raw: match[0],
+                            id,
+                            content,
+                            tokens: [],
+                        };
+                        this.lexer.inline(content, token.tokens);
+                        footnoteStore.definitions.set(id, { content, tokens: token.tokens });
+                        return token;
+                    }
+                    return undefined;
+                },
+                renderer() {
+                    // Definitions are rendered at the end, not inline
+                    return '';
+                },
+            },
+            // Footnote reference: [^id]
+            {
+                name: 'footnoteRef',
+                level: 'inline',
+                start(src) {
+                    return src.match(/\[\^[^\]]+\](?!:)/)?.index;
+                },
+                tokenizer(src) {
+                    const match = src.match(/^\[\^([^\]]+)\](?!:)/);
+                    if (match) {
+                        const id = match[1];
+                        footnoteStore.references.add(id);
+                        return {
+                            type: 'footnoteRef',
+                            raw: match[0],
+                            id,
+                        };
+                    }
+                    return undefined;
+                },
+                renderer(token) {
+                    return `<sup class="footnote-ref"><a href="#fn-${token.id}" id="fnref-${token.id}">[${token.id}]</a></sup>`;
+                },
+            },
+        ],
+    };
+}
+/**
+ * Render collected footnotes as a section
+ * Call this after parsing to get the footnotes HTML
+ */
+export function renderFootnotes() {
+    if (footnoteStore.definitions.size === 0) {
+        return '';
+    }
+    const items = [];
+    for (const [id, { content }] of footnoteStore.definitions) {
+        if (footnoteStore.references.has(id)) {
+            items.push(`<li id="fn-${id}" class="footnote-item">
+          <p>${content} <a href="#fnref-${id}" class="footnote-backref">↩</a></p>
+        </li>`);
+        }
+    }
+    if (items.length === 0) {
+        return '';
+    }
+    return `<section class="footnotes">
+  <hr class="footnotes-separator" />
+  <ol class="footnotes-list">${items.join('')}</ol>
+</section>`;
+}
+/**
+ * Definition list extension for marked
+ *
+ * Syntax:
+ * Term 1
+ * : Definition for term 1
+ *
+ * Term 2
+ * : Definition for term 2
+ * : Another definition for term 2
+ */
+export function definitionListExtension() {
+    return {
+        extensions: [
+            {
+                name: 'defList',
+                level: 'block',
+                start(src) {
+                    // Look for a term followed by : definition pattern
+                    return src.match(/^[^\n]+\n:\s/)?.index;
+                },
+                tokenizer(src) {
+                    // Match definition list blocks
+                    const match = src.match(/^((?:[^\n]+\n(?::\s+[^\n]*\n?)+\n?)+)/);
+                    if (match) {
+                        const raw = match[0];
+                        const items = [];
+                        // Parse individual term/definition pairs
+                        const lines = raw.split('\n');
+                        let currentTerm = '';
+                        let currentDefs = [];
+                        for (const line of lines) {
+                            if (line.startsWith(': ')) {
+                                // This is a definition
+                                currentDefs.push(line.slice(2).trim());
+                            }
+                            else if (line.trim() && !line.startsWith(':')) {
+                                // This is a new term
+                                if (currentTerm && currentDefs.length > 0) {
+                                    items.push({ term: currentTerm, definitions: [...currentDefs] });
+                                    currentDefs = [];
+                                }
+                                currentTerm = line.trim();
+                            }
+                        }
+                        // Don't forget the last item
+                        if (currentTerm && currentDefs.length > 0) {
+                            items.push({ term: currentTerm, definitions: currentDefs });
+                        }
+                        if (items.length === 0) {
+                            return undefined;
+                        }
+                        return {
+                            type: 'defList',
+                            raw,
+                            items,
+                        };
+                    }
+                    return undefined;
+                },
+                renderer(token) {
+                    const itemsHtml = token.items
+                        .map((item) => {
+                        const defsHtml = item.definitions.map((def) => `<dd>${def}</dd>`).join('');
+                        return `<dt>${item.term}</dt>${defsHtml}`;
+                    })
+                        .join('');
+                    return `<dl class="definition-list">${itemsHtml}</dl>`;
+                },
+            },
+        ],
+    };
+}
+/**
+ * Mermaid code block extension for marked
+ *
+ * Converts mermaid code blocks to placeholder divs that can be
+ * rendered client-side by the Mermaid library.
+ *
+ * Syntax:
+ * ```mermaid
+ * graph TD
+ *   A --> B
+ * ```
+ */
+export function mermaidExtension() {
+    return {
+        extensions: [
+            {
+                name: 'mermaidBlock',
+                level: 'block',
+                start(src) {
+                    return src.match(/^```mermaid/)?.index;
+                },
+                tokenizer(src) {
+                    const match = src.match(/^```mermaid\n([\s\S]*?)```/);
+                    if (match) {
+                        return {
+                            type: 'mermaidBlock',
+                            raw: match[0],
+                            code: match[1].trim(),
+                        };
+                    }
+                    return undefined;
+                },
+                renderer(token) {
+                    // Render as a placeholder div with the mermaid code
+                    // The client-side Mermaid library will pick this up
+                    const escapedCode = token.code
+                        .replace(/&/g, '&amp;')
+                        .replace(/</g, '&lt;')
+                        .replace(/>/g, '&gt;')
+                        .replace(/"/g, '&quot;');
+                    return `<div class="mermaid-diagram" data-mermaid="${escapedCode}">
+  <pre class="mermaid">${token.code}</pre>
+</div>`;
+                },
+            },
+        ],
+    };
+}
+/**
+ * Get all markdown extensions
+ */
+export function getAllExtensions() {
+    return [
+        admonitionExtension(),
+        footnoteExtension(),
+        definitionListExtension(),
+        mermaidExtension(),
+    ];
+}

package/dist/lib/parser/index.d.ts

@@ -0,0 +1,57 @@
+import type { ParsedMarkdown, ParseOptions } from '../types/index.js';
+/**
+ * Parse markdown content with YAML frontmatter extraction and syntax highlighting.
+ *
+ * Extracts YAML frontmatter from the beginning of the content (between `---` delimiters),
+ * applies Shiki syntax highlighting to code blocks, and optionally generates heading IDs.
+ *
+ * Supported extensions:
+ * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Footnotes: [^1] references and [^1]: definitions
+ * - Definition Lists: Term followed by : Definition
+ * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
+ *
+ * @param content - Raw markdown string, optionally with YAML frontmatter
+ * @param options - Parsing options
+ * @param options.theme - Shiki theme for code highlighting ('github-dark' | 'github-light' | 'one-dark-pro')
+ * @param options.generateHeadingIds - Whether to generate IDs for headings (default: true)
+ * @returns Parsed markdown with frontmatter data, cleaned markdown, and rendered HTML
+ *
+ * @example
+ * ```typescript
+ * const result = await parseMarkdown(`---
+ * title: My Document
+ * ---
+ * # Hello World
+ *
+ * :::tip Pro Tip
+ * This is a helpful tip!
+ * :::
+ * `);
+ * console.log(result.frontmatter?.title); // "My Document"
+ * console.log(result.html); // Contains heading and admonition HTML
+ * ```
+ */
+export declare function parseMarkdown(content: string, options?: ParseOptions): Promise<ParsedMarkdown>;
+/**
+ * Extract table of contents entries from rendered HTML content.
+ *
+ * Searches for heading elements (h1-h6) with `id` attributes and returns
+ * a flat array of entries. Headings without IDs are ignored.
+ *
+ * @param html - Rendered HTML string containing headings with IDs
+ * @param maxDepth - Maximum heading level to include (1-6, default: 3)
+ * @returns Flat array of TOC entries with text, level, and id
+ *
+ * @example
+ * ```typescript
+ * const html = '<h1 id="intro">Introduction</h1><h2 id="setup">Setup</h2>';
+ * const toc = extractToc(html, 2);
+ * // Returns: [{ text: 'Introduction', level: 1, id: 'intro' }, { text: 'Setup', level: 2, id: 'setup' }]
+ * ```
+ */
+export declare function extractToc(html: string, maxDepth?: number): {
+    text: string;
+    level: number;
+    id: string;
+}[];

package/dist/lib/parser/index.js

@@ -0,0 +1,150 @@
+import { marked, Renderer } from 'marked';
+import yaml from 'js-yaml';
+import { getHighlighter, escapeHtml } from '../highlighter/index.js';
+import { getAllExtensions, resetFootnoteStore, renderFootnotes } from './extensions.js';
+/**
+ * SECURITY NOTE: This parser renders markdown to HTML without sanitization.
+ * Only use with trusted markdown content from your own codebase or CMS.
+ * Do NOT use with user-generated content without adding a sanitization step.
+ */
+/**
+ * Extract frontmatter from markdown content
+ * Browser-compatible implementation using js-yaml
+ */
+function extractFrontmatter(content) {
+    const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        return { data: null, content };
+    }
+    try {
+        const data = yaml.load(match[1]);
+        return { data, content: match[2] };
+    }
+    catch (err) {
+        // Log warning for debugging - YAML parsing failed
+        console.warn('[docs] Failed to parse YAML frontmatter:', err instanceof Error ? err.message : err);
+        return { data: null, content };
+    }
+}
+/**
+ * Parse markdown content with YAML frontmatter extraction and syntax highlighting.
+ *
+ * Extracts YAML frontmatter from the beginning of the content (between `---` delimiters),
+ * applies Shiki syntax highlighting to code blocks, and optionally generates heading IDs.
+ *
+ * Supported extensions:
+ * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Footnotes: [^1] references and [^1]: definitions
+ * - Definition Lists: Term followed by : Definition
+ * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
+ *
+ * @param content - Raw markdown string, optionally with YAML frontmatter
+ * @param options - Parsing options
+ * @param options.theme - Shiki theme for code highlighting ('github-dark' | 'github-light' | 'one-dark-pro')
+ * @param options.generateHeadingIds - Whether to generate IDs for headings (default: true)
+ * @returns Parsed markdown with frontmatter data, cleaned markdown, and rendered HTML
+ *
+ * @example
+ * ```typescript
+ * const result = await parseMarkdown(`---
+ * title: My Document
+ * ---
+ * # Hello World
+ *
+ * :::tip Pro Tip
+ * This is a helpful tip!
+ * :::
+ * `);
+ * console.log(result.frontmatter?.title); // "My Document"
+ * console.log(result.html); // Contains heading and admonition HTML
+ * ```
+ */
+export async function parseMarkdown(content, options = {}) {
+    const { theme = 'github-dark', generateHeadingIds = true } = options;
+    // Extract frontmatter
+    const { data: frontmatter, content: markdownContent } = extractFrontmatter(content);
+    // Get Shiki highlighter
+    const highlighter = await getHighlighter();
+    // Reset footnote store for this document
+    resetFootnoteStore();
+    // Configure marked with custom code renderer
+    const renderer = new Renderer();
+    renderer.code = ({ text, lang }) => {
+        const language = lang || 'text';
+        // Skip mermaid blocks - they're handled by the mermaid extension
+        if (language === 'mermaid') {
+            return '';
+        }
+        try {
+            const highlighted = highlighter.codeToHtml(text, {
+                lang: language,
+                theme: theme,
+            });
+            return highlighted;
+        }
+        catch {
+            // Fallback for unsupported languages
+            return `<pre class="shiki"><code class="language-${language}">${escapeHtml(text)}</code></pre>`;
+        }
+    };
+    if (generateHeadingIds) {
+        renderer.heading = ({ text, depth }) => {
+            const id = text
+                .toLowerCase()
+                .replace(/\./g, '-') // Convert periods to hyphens (preserves version numbers like v2.0 → v2-0)
+                .replace(/[^\w\s-]+/g, '') // Remove other special characters
+                .replace(/\s+/g, '-') // Convert spaces to hyphens
+                .replace(/-+/g, '-') // Collapse multiple hyphens
+                .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+            return `<h${depth} id="${id}">${text}</h${depth}>`;
+        };
+    }
+    // Apply all markdown extensions (admonitions, footnotes, definition lists, mermaid)
+    marked.use(...getAllExtensions());
+    marked.use({ renderer, gfm: true });
+    let html = await marked(markdownContent);
+    // Append footnotes section if any were referenced
+    const footnotesHtml = renderFootnotes();
+    if (footnotesHtml) {
+        html += footnotesHtml;
+    }
+    return {
+        frontmatter,
+        markdown: markdownContent,
+        html,
+    };
+}
+/**
+ * Extract table of contents entries from rendered HTML content.
+ *
+ * Searches for heading elements (h1-h6) with `id` attributes and returns
+ * a flat array of entries. Headings without IDs are ignored.
+ *
+ * @param html - Rendered HTML string containing headings with IDs
+ * @param maxDepth - Maximum heading level to include (1-6, default: 3)
+ * @returns Flat array of TOC entries with text, level, and id
+ *
+ * @example
+ * ```typescript
+ * const html = '<h1 id="intro">Introduction</h1><h2 id="setup">Setup</h2>';
+ * const toc = extractToc(html, 2);
+ * // Returns: [{ text: 'Introduction', level: 1, id: 'intro' }, { text: 'Setup', level: 2, id: 'setup' }]
+ * ```
+ */
+export function extractToc(html, maxDepth = 3) {
+    const headingRegex = /<h([1-6])[^>]*id="([^"]*)"[^>]*>([^<]*)<\/h[1-6]>/gi;
+    const toc = [];
+    let match;
+    while ((match = headingRegex.exec(html)) !== null) {
+        const level = parseInt(match[1], 10);
+        if (level <= maxDepth) {
+            toc.push({
+                level,
+                id: match[2],
+                text: match[3],
+            });
+        }
+    }
+    return toc;
+}