markdown2typst 0.1.0

package/src/output-builder.ts

@@ -0,0 +1,229 @@
+/**
+ * Output building pipeline stage
+ * @module output-builder
+ */
+
+import type { Root, Content } from 'mdast';
+import type { DocumentMetadata, RenderContext } from './types.js';
+import { renderBlock } from './block-renderer.js';
+import { isNonEmpty, normalizeText, renderTypstArray, escapeTypstString } from './utils.js';
+import { parseDate } from './frontmatter.js';
+import { ErrorSeverity } from './types.js';
+
+/**
+ * Build the warnings section with custom functions for conversion issues.
+ * 
+ * @param context - Rendering context with warnings tracking
+ * @returns Warnings section as string, or null if no warnings
+ */
+function buildWarningsSection(context: RenderContext): string | null {
+	const { warnings } = context;
+	const sections: string[] = [];
+
+	// Add header if any warnings exist
+	const hasWarnings = warnings.externalImages;
+	if (!hasWarnings) return null;
+
+	sections.push('// ========================= WARNINGS =========================');
+	sections.push('');
+	sections.push('// ------------------------------------------------------------');
+	sections.push('// NOTE: The conversion did not work perfectly due to intrinsic');
+	sections.push('// Markdown to Typst limitations. The following custom');
+	sections.push('// functions, set or show rules are used to visually display');
+	sections.push('// these minor conversion warnings to the user.');
+	sections.push('// ------------------------------------------------------------');
+	sections.push('');
+
+	// Add external images function if needed
+	if (warnings.externalImages) {
+		sections.push('// EXTERNAL IMAGES WERE DETECTED!');
+		sections.push('#let external-image(url) = {');
+		sections.push('  rect(radius: 4pt, inset: 20pt,)[');
+		sections.push('    #align(center)[');
+		sections.push('      #text()[');
+		sections.push('        External image detected: \\');
+		sections.push('        #link(url)');
+		sections.push('      ]');
+		sections.push('    ]');
+		sections.push('  ]');
+		sections.push('}');
+		sections.push('');
+	}
+
+	sections.push('// ============================================================');
+
+	return sections.join('\n');
+}
+
+/**
+ * Build the final Typst document output.
+ * Combines metadata, frontmatter, and rendered body content.
+ * 
+ * @param tree - The parsed MDAST tree
+ * @param metadata - Merged document metadata
+ * @param leadingTitleIndex - Index of leading H1 (to skip in body), or null
+ * @param context - Rendering context with definitions and footnotes
+ * @returns Complete Typst document as string
+ */
+export function buildOutput(
+	tree: Root,
+	metadata: DocumentMetadata,
+	leadingTitleIndex: number | null,
+	context: RenderContext
+): string {
+	try {
+		const { title, authors, description, keywords, date, abstract, lang, region } = metadata;
+
+		// Filter out leading title if it matches the metadata title
+		const nodesForBody =
+			leadingTitleIndex !== null && normalizeText(title) !== ''
+				? tree.children.filter((_, index) => index !== leadingTitleIndex)
+				: tree.children;
+
+		// Render body content
+		const body = nodesForBody
+			.map((node) => renderBlock(node, 0, context))
+			.filter(isNonEmpty)
+			.join('\n\n');
+
+		// Build document metadata and configuration
+		const parts: string[] = [];
+
+		// Set document metadata if any metadata is available
+		const hasMetadata = title || authors.length > 0 || description || date || (keywords && keywords.length > 0);
+		if (hasMetadata) {
+			try {
+				parts.push('// ===============  FRONTMATTER  ===============');
+				parts.push('');
+				const docArgs: string[] = [];
+				
+				if (title) docArgs.push(`title: [${title}]`);
+				
+				if (authors.length > 0) {
+					docArgs.push(`author: ${renderTypstArray(authors.map(a => `"${escapeTypstString(a)}"`))}`)
+				}
+				
+				if (description) docArgs.push(`description: [${description}]`);
+				
+				if (keywords && keywords.length > 0) {
+					docArgs.push(`keywords: ${renderTypstArray(keywords.map(k => `"${escapeTypstString(k)}"`))}`)
+				}
+				
+				if (date) {
+					try {
+						const dateTypst = parseDate(date);
+						docArgs.push(`date: ${dateTypst}`);
+					} catch (error) {
+						const errorMessage = error instanceof Error ? error.message : String(error);
+						if (context.onError) {
+							context.onError({
+								severity: ErrorSeverity.WARNING,
+								message: `Failed to parse date "${date}": ${errorMessage}`,
+								context: 'output building',
+								originalError: error
+							});
+						}
+						// Use 'auto' as fallback
+						docArgs.push(`date: auto`);
+					}
+				}
+				
+				parts.push(`#set document(`);
+				for (let i = 0; i < docArgs.length; i++) {
+					const isLast = i === docArgs.length - 1;
+					parts.push(`  ${docArgs[i]}${isLast ? '' : ','}`);
+				}
+				parts.push(`)`);
+			} catch (error) {
+				const errorMessage = error instanceof Error ? error.message : String(error);
+				if (context.onError) {
+					context.onError({
+						severity: ErrorSeverity.ERROR,
+						message: `Error building document metadata: ${errorMessage}`,
+						context: 'output building',
+						originalError: error
+					});
+				}
+				// Continue without metadata
+			}
+		}
+
+		// Add abstract variable if present
+		if (abstract) {
+			if (parts.length > 0) parts.push('');
+			parts.push(`#let abstract = [${abstract}]`);
+		}
+
+		// Add title page if we have title or authors
+		if ((title || authors.length > 0 || date || abstract) && hasMetadata) {
+			parts.push('');
+			const centerLines: string[] = [];
+			
+			if (title) {
+				centerLines.push(`#title() \\ \\`);
+			}
+			
+			if (authors.length > 0) {
+				centerLines.push(`#context document.author.join(", ", last: " & ") \\ \\`);
+			}
+			
+			if (date) {
+				centerLines.push(`#context document.date.display() \\ \\ `);
+			}
+			
+			if (abstract) {
+				centerLines.push(`\\ *Abstract* \\`);
+				centerLines.push(`#abstract`);
+			}
+			
+			parts.push(`#align(center)[`);
+			parts.push(`  ${centerLines.join(' ')}`);
+			parts.push(`]`);
+		}
+
+		// Set text language and region if specified
+		if (lang || region) {
+			if (parts.length > 0) parts.push('');
+			const textArgs: string[] = [];
+			if (lang) textArgs.push(`lang: "${lang}"`);
+			if (region) textArgs.push(`region: "${region}"`);
+			parts.push(`#set text(${textArgs.join(', ')})`);
+		}
+
+		// Add closing comment for frontmatter section
+		if (hasMetadata) {
+			parts.push('');
+			parts.push('//  ============================================');
+		}
+
+		// Add warnings section if any warnings were detected
+		const warningsSection = buildWarningsSection(context);
+		if (warningsSection) {
+			parts.push('');
+			parts.push(warningsSection);
+		}
+
+		// Add body content
+		if (parts.length > 0 && body) {
+			parts.push('');
+		}
+		if (body) {
+			parts.push(body);
+		}
+
+		// Return body only if no metadata was set
+		return parts.length > 0 ? parts.join('\n') : body;
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		if (context.onError) {
+			context.onError({
+				severity: ErrorSeverity.ERROR,
+				message: `Fatal error building output: ${errorMessage}`,
+				context: 'output building',
+				originalError: error
+			});
+		}
+		// Rethrow fatal errors
+		throw error;
+	}
+}

package/src/parser.ts

@@ -0,0 +1,53 @@
+/**
+ * Markdown parsing pipeline stage
+ * @module parser
+ */
+
+import { unified } from 'unified';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import remarkParse from 'remark-parse';
+import type { Root } from 'mdast';
+import type { ErrorCallback } from './types.js';
+import { ErrorSeverity } from './types.js';
+
+/**
+ * Parse Markdown text into an MDAST tree.
+ * 
+ * This is the first stage of the conversion pipeline. It uses remark plugins to:
+ * - Parse basic Markdown syntax
+ * - Extract YAML frontmatter
+ * - Support GitHub Flavored Markdown (tables, strikethrough, etc.)
+ * - Parse LaTeX math equations
+ * 
+ * @param markdown - The Markdown text to parse
+ * @param onError - Optional error callback for logging parse issues
+ * @returns The parsed MDAST tree
+ */
+export function parseMarkdown(markdown: string, onError?: ErrorCallback): Root {
+	try {
+		const processor = unified()
+			.use(remarkParse)
+			.use(remarkFrontmatter, ['yaml'])
+			.use(remarkGfm, { singleTilde: false })
+			.use(remarkMath);
+
+		const parsedTree = processor.parse(markdown);
+		const tree = processor.runSync(parsedTree) as Root;
+		
+		return tree;
+	} catch (error) {
+		const errorMessage = error instanceof Error ? error.message : String(error);
+		if (onError) {
+			onError({
+				severity: ErrorSeverity.ERROR,
+				message: `Failed to parse Markdown: ${errorMessage}`,
+				context: 'markdown parsing',
+				originalError: error
+			});
+		}
+		// Rethrow the error after logging
+		throw error;
+	}
+}

package/src/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Type definitions for the markdown2typst library
+ * @module types
+ */
+
+import type {
+	Definition,
+	FootnoteDefinition,
+	Literal,
+	PhrasingContent
+} from 'mdast';
+
+/** Error severity levels for conversion warnings and errors */
+export enum ErrorSeverity {
+	/** Warning that doesn't prevent conversion but may affect output quality */
+	WARNING = 'warning',
+	/** Error that may result in incorrect or incomplete output */
+	ERROR = 'error'
+}
+
+/** Error information passed to error callback */
+export type ConversionError = {
+	/** Severity level of the error */
+	severity: ErrorSeverity;
+	/** Error message describing what went wrong */
+	message: string;
+	/** Context about where the error occurred (e.g., 'frontmatter parsing', 'math conversion') */
+	context: string;
+	/** Original error object if available */
+	originalError?: unknown;
+	/** Additional metadata about the error */
+	details?: Record<string, any>;
+};
+
+/** Callback function for handling conversion errors and warnings */
+export type ErrorCallback = (error: ConversionError) => void;
+
+/** Extended MDAST node type for marked/highlighted text */
+export interface Mark extends Literal {
+	type: 'mark';
+	children: PhrasingContent[];
+}
+
+/** Extended MDAST node type for superscript text */
+export interface SuperScript extends Literal {
+	type: 'superscript';
+	children: PhrasingContent[];
+}
+
+/** Extended MDAST node type for subscript text */
+export interface SubScript extends Literal {
+	type: 'subscript';
+	children: PhrasingContent[];
+}
+
+/** Extended MDAST node type for block-level math equations */
+export interface MathNode extends Literal {
+	type: 'math';
+}
+
+/** Extended MDAST node type for inline math equations */
+export interface InlineMathNode extends Literal {
+	type: 'inlineMath';
+}
+
+/**
+ * Options for configuring the Markdown to Typst conversion.
+ * All fields override corresponding frontmatter values if specified.
+ */
+export type Markdown2TypstOptions = {
+	/** Document title (overrides frontmatter) */
+	title?: string;
+	/** Document author(s) - single string or array (overrides frontmatter) */
+	author?: string | string[];
+	/** Document authors - alternative field name (overrides frontmatter) */
+	authors?: string[];
+	/** Document description (overrides frontmatter) */
+	description?: string;
+	/** Document keywords - array (overrides frontmatter) */
+	keywords?: string[];
+	/** Document date - string, 'auto', or ISO date (overrides frontmatter) */
+	date?: string;
+	/** Document abstract - rendered on title page (overrides frontmatter) */
+	abstract?: string;
+	/** Document language code (ISO 639 standard) (overrides frontmatter) */
+	lang?: string;
+	/** Alternative language field name (overrides frontmatter) */
+	language?: string;
+	/** Text region code (overrides frontmatter) */
+	region?: string;
+	/** Use leading H1 heading as document title (default: false) */
+	useH1AsTitle?: boolean;
+	/** Callback function for handling errors and warnings during conversion */
+	onError?: ErrorCallback;
+};
+
+/**
+ * Metadata extracted from YAML frontmatter.
+ * Follows Typst document() parameters specification.
+ * All fields are optional. Unknown fields are ignored.
+ */
+export type Frontmatter = {
+	/** Document title (maps to document.title) */
+	title?: string;
+	/** Document author(s) - single string or array (maps to document.author) */
+	author?: string | string[];
+	/** Document authors - alternative field name (maps to document.author) */
+	authors?: string[];
+	/** Document description (maps to document.description) */
+	description?: string;
+	/** Document keywords - array (maps to document.keywords) */
+	keywords?: string[];
+	/** Document date - string, 'auto', or ISO date (maps to document.date) */
+	date?: string;
+	/** Document abstract - rendered on title page */
+	abstract?: string;
+	/** Document language code (maps to text.lang, not document parameter) */
+	lang?: string;
+	/** Alternative language field name */
+	language?: string;
+	/** Text region code (maps to text.region) */
+	region?: string;
+};
+
+/**
+ * Merged document metadata after combining options and frontmatter
+ */
+export type DocumentMetadata = {
+	title: string;
+	authors: string[];
+	description?: string;
+	keywords?: string[];
+	date?: string;
+	abstract?: string;
+	lang?: string;
+	region?: string;
+};
+
+/**
+ * Warnings that can be tracked during conversion
+ */
+export type ConversionWarnings = {
+	/** Whether external images were detected */
+	externalImages: boolean;
+};
+
+/**
+ * Context for rendering nodes
+ */
+export type RenderContext = {
+	definitions: Map<string, Definition>;
+	footnoteDefinitions: Map<string, FootnoteDefinition>;
+	onError?: ErrorCallback;
+	/** Track conversion warnings for generating helper functions */
+	warnings: ConversionWarnings;
+};

package/src/utils.ts

@@ -0,0 +1,241 @@
+/**
+ * Utility functions for text processing and formatting
+ * @module utils
+ */
+
+import langs from 'langs';
+import { getCode, getCodes } from 'country-list';
+import type { Definition, PhrasingContent, Text, InlineCode, Strong, Link, LinkReference } from 'mdast';
+
+/**
+ * Escape special characters in Typst text content.
+ * Escapes characters that have special meaning in Typst markup.
+ * 
+ * @param input - Raw text string
+ * @returns Escaped text safe for Typst
+ */
+export function escapeTypstText(input: string): string {
+	try {
+		return input.replace(/[\\#*_`\[\]\$<>@]/g, (c) => `\\${c}`);
+	} catch (error) {
+		// Fallback: return original string if escaping fails
+		return input;
+	}
+}
+
+/**
+ * Escape special characters in Typst string literals.
+ * Used for strings within quotes (URLs, titles, etc.).
+ * 
+ * @param input - Raw string
+ * @returns Escaped string safe for Typst string literals
+ */
+export function escapeTypstString(input: string): string {
+	try {
+		return input.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+	} catch (error) {
+		// Fallback: return original string if escaping fails
+		return input;
+	}
+}
+
+/**
+ * Indent all lines of text by a given level.
+ * Each indent level adds 2 spaces.
+ * 
+ * @param text - Text to indent
+ * @param indentLevel - Number of indent levels (0 = no indent)
+ * @returns Indented text
+ */
+export function indentLines(text: string, indentLevel: number): string {
+	if (!indentLevel) return text;
+	const indent = '  '.repeat(indentLevel);
+	return text
+		.split('\n')
+		.map((line) => `${indent}${line}`)
+		.join('\n');
+}
+
+/**
+ * Type guard to check if a value is a non-empty string.
+ * Useful for filtering arrays.
+ * 
+ * @param value - Value to check
+ * @returns True if value is a non-empty string
+ */
+export function isNonEmpty(value: string | null | undefined): value is string {
+	return typeof value === 'string' && value.length > 0;
+}
+
+/**
+ * Normalize text by trimming whitespace.
+ * 
+ * @param value - Text to normalize
+ * @returns Trimmed text
+ */
+export function normalizeText(value: string | null): string {
+	return (value ?? '').trim();
+}
+
+/**
+ * Extract plain text content from phrasing nodes (inline content).
+ * Strips all formatting and extracts text only.
+ * 
+ * @param nodes - Array of phrasing content nodes
+ * @param definitions - Map of link reference definitions
+ * @returns Plain text string
+ */
+export function plainTextFromPhrasing(nodes: PhrasingContent[], definitions: Map<string, Definition>): string {
+	return nodes.map((node) => plainTextFromPhrasingNode(node, definitions)).join('');
+}
+
+function plainTextFromPhrasingNode(node: PhrasingContent, definitions: Map<string, Definition>): string {
+	switch (node.type) {
+		case 'text':
+			return (node as Text).value;
+		case 'strong':
+		case 'emphasis':
+			return plainTextFromPhrasing((node as Strong).children, definitions);
+		case 'inlineCode':
+			return (node as InlineCode).value;
+		case 'link':
+			return plainTextFromPhrasing((node as Link).children, definitions);
+		case 'linkReference': {
+			const lr = node as LinkReference;
+			const label = plainTextFromPhrasing(lr.children, definitions);
+			if (label.trim()) return label;
+			const def = definitions.get(lr.identifier.toLowerCase());
+			return def ? def.url : lr.label || lr.identifier;
+		}
+		case 'break':
+			return '\n';
+		default:
+			return '';
+	}
+}
+
+/**
+ * Render a Typst-style tuple array.
+ * Ensures proper syntax for single-element arrays (requires trailing comma).
+ * 
+ * @param items - Array items as strings
+ * @returns Formatted Typst array syntax
+ */
+export function renderTypstArray(items: string[]): string {
+	if (items.length === 1) return `(${items[0]},)`;
+	return `(${items.join(', ')})`;
+}
+
+/**
+ * Calculate the maximum consecutive backtick run in a string.
+ * Used to determine the fence length for code blocks.
+ * 
+ * @param value - String to analyze
+ * @returns Maximum consecutive backtick count
+ */
+export function maxBacktickRun(value: string): number {
+	let maxRun = 0;
+	let run = 0;
+	for (let i = 0; i < value.length; i++) {
+		if (value[i] === '`') {
+			run++;
+			if (run > maxRun) maxRun = run;
+			continue;
+		}
+		run = 0;
+	}
+	return maxRun;
+}
+
+/**
+ * Coerce language string to valid ISO 639 language code.
+ * 
+ * Validates and normalizes language codes using ISO 639-1 standard.
+ * Supports various input formats:
+ * - ISO 639-1 codes (e.g., 'en', 'zh', 'fr')
+ * - Locale codes (e.g., 'en-US', 'zh-CN') - extracts language part
+ * - Language names (e.g., 'English', 'Chinese') - looks up code
+ * 
+ * @param value - Language string or code
+ * @returns Normalized ISO 639-1 language code or undefined if invalid
+ */
+export function coerceLanguage(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	
+	const v = value.trim();
+	if (!v) return undefined;
+	
+	// Extract language code from locale format (e.g., 'en-US' -> 'en', 'zh-CN' -> 'zh')
+	const langPart = v.split(/[-_]/)[0].toLowerCase();
+	
+	// Try to validate as ISO 639-1 code (2-letter)
+	const iso1Codes = langs.codes('1');
+	if (iso1Codes.includes(langPart)) {
+		return langPart;
+	}
+	
+	// Try to look up by language name (case-insensitive)
+	const allLangs = langs.all();
+	for (const lang of allLangs) {
+		if (lang.name && lang.name.toLowerCase() === v.toLowerCase() && lang['1']) {
+			return lang['1'];
+		}
+		// Also check local name if available
+		if (lang.local && lang.local.toLowerCase() === v.toLowerCase() && lang['1']) {
+			return lang['1'];
+		}
+	}
+	
+	// Try ISO 639-2 or 639-3 codes and convert to ISO 639-1
+	const langBy2 = langs.where('2', v.toLowerCase());
+	if (langBy2 && langBy2['1']) {
+		return langBy2['1'];
+	}
+	
+	const langBy2B = langs.where('2B', v.toLowerCase());
+	if (langBy2B && langBy2B['1']) {
+		return langBy2B['1'];
+	}
+	
+	const langBy3 = langs.where('3', v.toLowerCase());
+	if (langBy3 && langBy3['1']) {
+		return langBy3['1'];
+	}
+	
+	// If no valid code found, return undefined
+	return undefined;
+}
+
+/**
+ * Coerce region string to valid ISO 3166 country code.
+ * 
+ * Validates and normalizes region/country codes using ISO 3166-1 alpha-2 standard.
+ * Supports various input formats:
+ * - ISO 3166-1 alpha-2 codes (e.g., 'US', 'CN', 'GB')
+ * - Country names (e.g., 'United States', 'China') - looks up code
+ * 
+ * @param value - Region/country string or code
+ * @returns Normalized ISO 3166-1 alpha-2 country code or undefined if invalid
+ */
+export function coerceRegion(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	
+	const v = value.trim();
+	if (!v) return undefined;
+	
+	// Check if it's already a valid ISO 3166-1 alpha-2 code
+	const upperValue = v.toUpperCase();
+	const validCodes = getCodes();
+	if (validCodes.includes(upperValue)) {
+		return upperValue;
+	}
+	
+	// Try to look up by country name
+	const code = getCode(v);
+	if (code) {
+		return code.toUpperCase();
+	}
+	
+	// If no valid code found, return undefined
+	return undefined;
+}