markdown2typst 0.1.0

package/src/frontmatter.ts

@@ -0,0 +1,197 @@
+/**
+ * Frontmatter parsing and custom options metadata handling pipeline stage
+ * @module frontmatter
+ */
+
+import { load as parseYaml } from 'js-yaml';
+import type { Root, Yaml } from 'mdast';
+import type { Frontmatter, Markdown2TypstOptions, DocumentMetadata, ErrorCallback } from './types.js';
+import { ErrorSeverity } from './types.js';
+import { coerceLanguage, coerceRegion } from './utils.js';
+
+/**
+ * Parse YAML frontmatter from the document.
+ * Supports title, authors (single or array), and language fields.
+ * 
+ * @param root - The root node of the MDAST tree
+ * @param onError - Optional error callback for logging parse issues
+ * @returns Parsed frontmatter metadata
+ */
+export function parseFrontmatter(root: Root, onError?: ErrorCallback): Frontmatter {
+	const yamlNode = root.children.find((node) => node.type === 'yaml') as Yaml | undefined;
+	if (!yamlNode?.value) return {};
+	return parseFrontmatterYaml(yamlNode.value, onError);
+}
+
+/**
+ * Parse YAML frontmatter string into structured metadata.
+ * Handles standard Markdown/Pandoc frontmatter fields using js-yaml.
+ * 
+ * @param yaml - Raw YAML string from frontmatter
+ * @param onError - Optional error callback for logging parse issues
+ * @returns Parsed frontmatter object
+ */
+function parseFrontmatterYaml(yaml: string, onError?: ErrorCallback): Frontmatter {
+	try {
+		const parsed = parseYaml(yaml) as Record<string, any>;
+		if (!parsed || typeof parsed !== 'object') {
+			if (onError) {
+				onError({
+					severity: ErrorSeverity.WARNING,
+					message: 'YAML frontmatter is empty or not an object',
+					context: 'frontmatter parsing'
+				});
+			}
+			return {};
+		}
+
+		const result: Frontmatter = {};
+
+		// Extract and normalize all supported fields
+		if ('title' in parsed && typeof parsed.title === 'string') {
+			result.title = parsed.title;
+		}
+
+		// Handle author field (can be string or array)
+		if ('author' in parsed) {
+			if (typeof parsed.author === 'string') {
+				result.author = parsed.author;
+			} else if (Array.isArray(parsed.author)) {
+				result.author = parsed.author.filter(a => typeof a === 'string');
+			} else if (onError) {
+				onError({
+					severity: ErrorSeverity.WARNING,
+					message: 'Frontmatter "author" field must be a string or array of strings',
+					context: 'frontmatter parsing',
+					details: { fieldType: typeof parsed.author }
+				});
+			}
+		}
+
+		// Handle authors field (array)
+		if ('authors' in parsed && Array.isArray(parsed.authors)) {
+			result.authors = parsed.authors.filter(a => typeof a === 'string');
+		}
+
+		// Description
+		if ('description' in parsed && typeof parsed.description === 'string') {
+			result.description = parsed.description;
+		}
+
+		// Keywords (array)
+		if ('keywords' in parsed && Array.isArray(parsed.keywords)) {
+			result.keywords = parsed.keywords.filter(k => typeof k === 'string');
+		}
+
+		// Date (string or Date object)
+		if ('date' in parsed) {
+			if (typeof parsed.date === 'string') {
+				result.date = parsed.date;
+			} else if (parsed.date instanceof Date) {
+				result.date = parsed.date.toISOString().split('T')[0]; // Convert to YYYY-MM-DD
+			}
+		}
+
+		// Abstract
+		if ('abstract' in parsed && typeof parsed.abstract === 'string') {
+			result.abstract = parsed.abstract;
+		}
+
+		// Language (lang or language)
+		if ('lang' in parsed && typeof parsed.lang === 'string') {
+			result.lang = parsed.lang;
+		}
+		if ('language' in parsed && typeof parsed.language === 'string') {
+			result.language = parsed.language;
+		}
+
+		// Region
+		if ('region' in parsed && typeof parsed.region === 'string') {
+			result.region = parsed.region;
+		}
+
+		return result;
+	} catch (error) {
+		// If YAML parsing fails, return empty frontmatter
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		if (onError) {
+			onError({
+				severity: ErrorSeverity.WARNING,
+				message: `Failed to parse YAML frontmatter: ${errorMessage}`,
+				context: 'frontmatter parsing',
+				originalError: error
+			});
+		}
+		return {};
+	}
+}
+
+/**
+ * Parse date string into Typst date format.
+ * Supports 'auto', 'none', and ISO date formats (YYYY-MM-DD).
+ * 
+ * @param value - Date string from frontmatter
+ * @returns Typst date expression
+ */
+export function parseDate(value: string): string {
+	const v = value.trim().toLowerCase();
+	
+	// Handle special values
+	if (v === 'auto') return 'auto';
+	if (v === 'none') return 'none';
+	
+	// Try to parse ISO date format (YYYY-MM-DD)
+	const isoMatch = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(value.trim());
+	if (isoMatch) {
+		const year = parseInt(isoMatch[1], 10);
+		const month = parseInt(isoMatch[2], 10);
+		const day = parseInt(isoMatch[3], 10);
+		return `datetime(day: ${day}, month: ${month}, year: ${year})`;
+	}
+	
+	// Default to auto if we can't parse the date
+	return 'auto';
+}
+
+/**
+ * Merge options with frontmatter to create final document metadata.
+ * Options take precedence over frontmatter values.
+ * 
+ * @param options - User-provided options
+ * @param frontmatter - Parsed frontmatter
+ * @param leadingTitle - Title from leading H1, if any
+ * @returns Merged document metadata
+ */
+export function mergeMetadata(
+	options: Markdown2TypstOptions,
+	frontmatter: Frontmatter,
+	leadingTitle: string | null
+): DocumentMetadata {
+	const title = options.title ?? frontmatter.title ?? leadingTitle ?? '';
+	
+	// Normalize authors from options and frontmatter (all optional)
+	const optionsAuthors = options.authors ?? 
+		(typeof options.author === 'string' ? [options.author] : options.author) ?? [];
+	const frontmatterAuthors = frontmatter.authors ?? 
+		(typeof frontmatter.author === 'string' ? [frontmatter.author] : frontmatter.author) ?? [];
+	const authors = optionsAuthors.length > 0 ? optionsAuthors : frontmatterAuthors;
+	
+	// Use options as overrides for all other fields
+	const lang = coerceLanguage(options.lang ?? options.language ?? frontmatter.lang ?? frontmatter.language);
+	const region = coerceRegion(options.region ?? frontmatter.region);
+	const date = options.date ?? frontmatter.date;
+	const description = options.description ?? frontmatter.description;
+	const keywords = options.keywords ?? frontmatter.keywords;
+	const abstract = options.abstract ?? frontmatter.abstract;
+
+	return {
+		title,
+		authors,
+		description,
+		keywords,
+		date,
+		abstract,
+		lang,
+		region
+	};
+}

package/src/inline-renderer.ts

@@ -0,0 +1,266 @@
+/**
+ * Inline node rendering functions
+ * @module inline-renderer
+ */
+
+import { tex2typst } from 'tex2typst';
+import type {
+	PhrasingContent,
+	Text,
+	Strong,
+	Emphasis,
+	Delete,
+	InlineCode,
+	Link,
+	LinkReference,
+	Image,
+	FootnoteReference,
+	Html
+} from 'mdast';
+import type { Mark, SuperScript, SubScript, InlineMathNode, RenderContext } from './types.js';
+import { escapeTypstText, escapeTypstString, isNonEmpty } from './utils.js';
+import { ErrorSeverity } from './types.js';
+
+/**
+ * Render inline phrasing nodes to Typst markup.
+ * 
+ * @param nodes - Array of phrasing content nodes
+ * @param context - Rendering context with definitions and footnotes
+ * @returns Rendered Typst string
+ */
+export function renderInlines(
+	nodes: PhrasingContent[],
+	context: RenderContext
+): string {
+	return nodes
+		.map((node) => renderInline(node, context))
+		.filter(isNonEmpty)
+		.join('');
+}
+
+/**
+ * Render an inline phrasing node to Typst markup.
+ * Handles text, emphasis, strong, code, links, images, math, etc.
+ * 
+ * @param node - Phrasing content node
+ * @param context - Rendering context with definitions and footnotes
+ * @returns Rendered Typst string or null if node should be skipped
+ */
+function renderInline(
+	node: PhrasingContent,
+	context: RenderContext
+): string | null {
+	const { definitions, footnoteDefinitions } = context;
+
+	switch ((node as any).type) {
+		case 'text':
+			return escapeTypstText((node as Text).value);
+		case 'strong':
+		return `*${renderInlines((node as Strong).children, context)}*`;
+		case 'emphasis':
+		return `_${renderInlines((node as Emphasis).children, context)}_`;
+		case 'delete':
+			return `#strike[${renderInlines((node as unknown as Delete).children, context)}]`;
+		case 'mark':
+			return `#highlight[${renderInlines((node as unknown as Mark).children, context)}]`;
+		case 'subscript':
+			return `#sub[${renderInlines((node as unknown as SubScript).children, context)}]`;
+		case 'superscript':
+			return `#super[${renderInlines((node as unknown as SuperScript).children, context)}]`;
+		case 'footnoteReference': {
+			const ref = node as FootnoteReference;
+			const def = footnoteDefinitions.get(ref.identifier.toLowerCase());
+			if (!def) {
+				if (context.onError) {
+					context.onError({
+						severity: ErrorSeverity.WARNING,
+						message: `Footnote reference [^${ref.identifier}] has no matching definition`,
+						context: 'inline rendering',
+						details: { identifier: ref.identifier }
+					});
+				}
+				return ''; // Or render as plain text?
+			}
+			// Render footnote content inline
+			try {
+				const content = def.children
+					.map((child) => {
+						// Import renderBlock only when needed to avoid circular dependencies
+						const { renderBlock } = require('./block-renderer.js');
+						return renderBlock(child, 0, context);
+					})
+					.filter(isNonEmpty)
+					.join(' '); // Join blocks with space for inline footnote
+				return `#footnote[${content.trim()}]`;
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : String(error);
+				if (context.onError) {
+					context.onError({
+						severity: ErrorSeverity.ERROR,
+						message: `Error rendering footnote [^${ref.identifier}]: ${errorMessage}`,
+						context: 'inline rendering',
+						originalError: error
+					});
+				}
+				return '';
+			}
+		}
+		case 'inlineCode':
+			return renderInlineCode(node as InlineCode);
+		case 'inlineMath': {
+			// Convert LaTeX to Typst math syntax
+			const mathNode = node as InlineMathNode;
+			const value = mathNode.value.trim();
+			
+			try {
+				const typstMath = tex2typst(value);
+				
+				// Check if this was originally $$...$$ (display/block math) or $...$ (inline math)
+				const isDisplayMath = mathNode.position?.end?.offset != null && 
+					mathNode.position?.start?.offset != null &&
+					(mathNode.position.end.offset - mathNode.position.start.offset) >= value.length + 4;
+				
+				// Display math ($$): use spaces for block-style rendering
+				// Inline math ($): no spaces for inline rendering
+				return isDisplayMath ? `$ ${typstMath} $` : `$${typstMath}$`;
+			} catch (error) {
+				// Fallback: use original LaTeX if conversion fails
+				const errorMessage = error instanceof Error ? error.message : String(error);
+				if (context.onError) {
+					context.onError({
+						severity: ErrorSeverity.WARNING,
+						message: `Failed to convert inline math LaTeX to Typst: ${errorMessage}`,
+						context: 'inline math rendering',
+						originalError: error,
+						details: { latex: value }
+					});
+				}
+				const isDisplayMath = mathNode.position?.end?.offset != null && 
+					mathNode.position?.start?.offset != null &&
+					(mathNode.position.end.offset - mathNode.position.start.offset) >= value.length + 4;
+				return isDisplayMath ? `$ ${value} $` : `$${value}$`;
+			}
+		}
+		case 'image':
+			return renderImage(node as Image, context);
+		case 'link':
+			return renderLink(node as Link, context);
+		case 'linkReference':
+			return renderLinkReference(node as LinkReference, context);
+		case 'break':
+			return '\\\n';
+		case 'html':
+			// Treat inline HTML as literal text, escape it for Typst
+			return escapeTypstText((node as Html).value);
+		default:
+			return null;
+	}
+}
+
+/**
+ * Render inline code to Typst.
+ * Escapes backticks within the code.
+ * 
+ * @param node - InlineCode node
+ * @returns Rendered Typst inline code
+ */
+function renderInlineCode(node: InlineCode): string {
+	const value = node.value.replace(/`/g, '\\`');
+	return `\`${value}\``;
+}
+
+/**
+ * Render an image to Typst.
+ * Uses Typst's #image() function for local images,
+ * and #external-image() for external (http/https) images.
+ * 
+ * @param node - Image node
+ * @param context - Rendering context with warnings tracking
+ * @returns Rendered Typst image function
+ */
+function renderImage(node: Image, context: RenderContext): string {
+	// Check if image is external (starts with http:// or https://)
+	const isExternal = /^https?:\/\//i.test(node.url);
+	
+	if (isExternal) {
+		// Mark that external images were detected
+		context.warnings.externalImages = true;
+		
+		try {
+			return `#external-image(\n  "${escapeTypstString(node.url)}"\n)`;
+		} catch (error) {
+			// Return unescaped URL if escaping fails
+			return `#external-image(\n  "${node.url}"\n)`;
+		}
+	} else {
+		// Local image - use standard #image() function
+		try {
+			return `#image("${escapeTypstString(node.url)}")`;
+		} catch (error) {
+			// Return unescaped URL if escaping fails
+			return `#image("${node.url}")`;
+		}
+	}
+}
+
+/**
+ * Render a link to Typst.
+ * Uses Typst's #link() function with URL and label.
+ * 
+ * @param node - Link node
+ * @param context - Rendering context with definitions and footnotes
+ * @returns Rendered Typst link
+ */
+function renderLink(
+	node: Link,
+	context: RenderContext
+): string {
+	const url = escapeTypstString(node.url);
+	const label = renderInlines(node.children, context);
+	if (!label.trim()) return `#link("${url}")[${escapeTypstText(node.url)}]`;
+	return `#link("${url}")[${label}]`;
+}
+
+/**
+ * Render a reference-style link to Typst.
+ * Resolves the reference to get the URL, then renders like a normal link.
+ * 
+ * @param node - LinkReference node
+ * @param context - Rendering context with definitions and footnotes
+ * @returns Rendered Typst link or fallback text
+ */
+function renderLinkReference(
+	node: LinkReference,
+	context: RenderContext
+): string | null {
+	const { definitions } = context;
+	const def = definitions.get(node.identifier.toLowerCase());
+	const label = renderInlines(node.children, context);
+	if (!def) {
+		if (context.onError) {
+			context.onError({
+				severity: ErrorSeverity.WARNING,
+				message: `Link reference [${node.identifier}] has no matching definition`,
+				context: 'inline rendering',
+				details: { identifier: node.identifier }
+			});
+		}
+		return label || escapeTypstText(node.label || node.identifier);
+	}
+	try {
+		const url = escapeTypstString(def.url);
+		if (!label.trim()) return `#link("${url}")[${escapeTypstText(def.url)}]`;
+		return `#link("${url}")[${label}]`;
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		if (context.onError) {
+			context.onError({
+				severity: ErrorSeverity.ERROR,
+				message: `Error rendering link reference [${node.identifier}]: ${errorMessage}`,
+				context: 'inline rendering',
+				originalError: error
+			});
+		}
+		return label || escapeTypstText(node.label || node.identifier);
+	}
+}

package/src/markdown2typst.ts

@@ -0,0 +1,96 @@
+/**
+ * markdown2typst - Convert Markdown to Typst
+ * 
+ * A comprehensive library for converting Markdown documents to Typst markup language.
+ * Supports GitHub Flavored Markdown, math equations, tables, footnotes, and more
+ * 
+ * This code is inspired by the original work of zhaoyiqun (Creator of MDXport; 'cosformula' on GitHub).
+ * Refactored, documented, modified and extended by Mapaor.
+ * 
+ * @module markdown2typst
+ * @license MIT
+ */
+
+import { ErrorSeverity, type Markdown2TypstOptions } from './types.js';
+import { parseMarkdown } from './parser.js';
+import { collectDefinitions, collectFootnotes, findLeadingH1 } from './collectors.js';
+import { parseFrontmatter, mergeMetadata } from './frontmatter.js';
+import { buildOutput } from './output-builder.js';
+
+// Re-export types for public API
+export type { Markdown2TypstOptions, ConversionError, ErrorCallback } from './types.js';
+export { ErrorSeverity } from './types.js';
+
+/**
+ * Convert Markdown text to Typst markup.
+ * 
+ * This is the main entry point for the library. It parses the Markdown using remark,
+ * processes frontmatter and metadata, and converts the AST to Typst syntax.
+ * 
+ * The conversion pipeline consists of several stages:
+ * 1. Parse Markdown into an AST (Abstract Syntax Tree)
+ * 2. Collect link/image definitions and footnotes
+ * 3. Parse YAML frontmatter and merge with options
+ * 4. Render AST nodes to Typst markup
+ * 5. Build final output with metadata and body
+ * 
+ * @param markdown - The Markdown text to convert
+ * @param options - Optional configuration for the conversion
+ * @returns The converted Typst markup as a string
+ * 
+ * @example
+ * ```typescript
+ * const typst = markdown2typst('# Hello\n\nThis is **bold**.');
+ * console.log(typst);
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * const typst = markdown2typst(markdown, {
+ *   title: 'My Document',
+ *   authors: ['John Doe'],
+ *   lang: 'en'
+ * });
+ * ```
+ */
+export function markdown2typst(markdown: string, options: Markdown2TypstOptions = {}): string {
+	try {
+		// Stage 1: Parse Markdown into AST
+		const tree = parseMarkdown(markdown, options.onError);
+
+		// Stage 2: Collect definitions and footnotes from the AST
+		const definitions = collectDefinitions(tree, options.onError);
+		const footnoteDefinitions = collectFootnotes(tree, options.onError);
+
+		// Stage 3: Parse frontmatter and extract leading title (if enabled)
+		const frontmatter = parseFrontmatter(tree, options.onError);
+		const leadingH1 = options.useH1AsTitle
+			? findLeadingH1(tree, definitions, options.onError)
+			: null;
+
+		// Stage 4: Merge metadata from options, frontmatter, and leading H1
+		const metadata = mergeMetadata(options, frontmatter, leadingH1?.title ?? null);
+
+		// Stage 5: Build final Typst output
+		const context = {
+			definitions,
+			footnoteDefinitions,
+			onError: options.onError,
+			warnings: { externalImages: false }
+		};
+		return buildOutput(tree, metadata, leadingH1?.index ?? null, context);
+	} catch (error) {
+		// Handle unexpected fatal errors
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		if (options.onError) {
+			options.onError({
+				severity: ErrorSeverity.ERROR,
+				message: `Fatal error during conversion: ${errorMessage}`,
+				context: 'markdown2typst',
+				originalError: error
+			});
+		}
+		// Rethrow fatal errors after logging
+		throw error;
+	}
+}