legal-markdown-js
Version:
Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version
213 lines • 7.63 kB
TypeScript
/**
* HTML Generation Module for Legal Markdown Documents
*
* This module provides functionality to convert processed Legal Markdown content
* into well-formatted HTML documents with CSS styling, accessibility features,
* and print optimization.
*
* Features:
* - Markdown to HTML conversion using marked
* - DOM manipulation with cheerio for enhanced formatting
* - Custom CSS injection and styling
* - Field highlighting for document review
* - Print-friendly output with page break controls
* - Responsive table handling
* - Accessibility improvements
*
* @example
* ```typescript
* import { htmlGenerator } from './html-generator.js';
*
* const html = await htmlGenerator.generateHtml(markdownContent, {
* title: 'Legal Agreement',
* cssPath: './styles.css',
* includeHighlighting: true
* });
* ```
*
* @module
*/
import * as cheerio from 'cheerio';
import type { MarkdownString, HtmlString } from '../../types/content-formats.js';
/**
* Configuration options for HTML generation
*
* @interface HtmlGeneratorOptions
*/
export interface HtmlGeneratorOptions {
/** Path to custom CSS file to include in the generated HTML */
cssPath?: string;
/** Path to highlighting CSS file for field highlighting */
highlightCssPath?: string;
/** Whether to include field highlighting styles */
includeHighlighting?: boolean;
/** Document title for the HTML page */
title?: string;
/** Additional metadata to include in HTML head (only primitive values are rendered as meta tags) */
metadata?: Record<string, unknown>;
}
/**
* HTML Generator for Legal Markdown Documents
*
* Converts processed Legal Markdown content into formatted HTML documents
* with professional styling, accessibility features, and print optimization.
*
* @class HtmlGenerator
* @example
* ```typescript
* const generator = new HtmlGenerator();
* const html = await generator.generateHtml(content, {
* title: 'Contract',
* includeHighlighting: true
* });
* ```
*/
export declare class HtmlGenerator {
/**
* Creates a new HTML generator instance and configures the markdown parser
*/
constructor();
/**
* Configures the marked markdown parser with options optimized for legal documents.
* Uses shared configuration from html-format.ts, then adds the Node-specific
* custom code renderer for preserving HTML spans in code blocks.
*
* @private
*/
private configureMarked;
/**
* Removes YAML frontmatter from markdown content if present
*
* @private
* @param {string} content - The markdown content that may contain YAML frontmatter
* @returns {string} Content with YAML frontmatter removed
* @example
* ```typescript
* const content = `---
* title: Document
* ---
* # Content`;
* const clean = this.removeYamlFrontmatter(content); // "# Content"
* ```
*/
private removeYamlFrontmatter;
/**
* Generates a complete HTML document from Legal Markdown content
*
* This is the main method that orchestrates the conversion process:
* 1. Removes YAML frontmatter
* 2. Converts markdown to HTML using marked
* 3. Applies DOM transformations for legal document formatting
* 4. Injects custom CSS and styling
* 5. Builds a complete HTML document
*
* @param {MarkdownString} markdownContent - The processed Legal Markdown content to convert (MUST be Markdown, NOT HTML)
* @param {HtmlGeneratorOptions} [options={}] - Configuration options for HTML generation
* @returns {Promise<HtmlString>} A promise that resolves to the complete HTML document
* @throws {Error} When HTML generation fails due to parsing or file system errors
* @throws {Error} When HTML content is detected instead of Markdown (indicates a bug)
*
* @example
* ```typescript
* import { asMarkdown } from '../../types/content-formats.js';
*
* // ✅ CORRECT - Pass Markdown
* const html = await generator.generateHtml(
* asMarkdown('# Contract\n\nThis is a {{party.name}} agreement.'),
* {
* title: 'Service Agreement',
* cssPath: './contract-styles.css',
* includeHighlighting: true,
* metadata: {
* author: 'Legal Team',
* version: '1.0'
* }
* }
* );
*
* // ❌ INCORRECT - Don't pass HTML
* const html = await generator.generateHtml(
* '<h1>Contract</h1>', // This will throw an error!
* {}
* );
* ```
*/
generateHtml(markdownContent: MarkdownString, options?: HtmlGeneratorOptions): Promise<HtmlString>;
/**
* Applies DOM transformations to enhance the HTML for legal document presentation
*
* Transformations include:
* - Adding no-break classes to short lists for better print layout
* - Wrapping tables in responsive containers
* - Adding alt attributes to images for accessibility
* - Adding print-friendly CSS classes
* - Cleaning up paragraph tags in list items
*
* @private
* @param {cheerio.CheerioAPI} $ - The cheerio instance with loaded HTML
* @returns {void}
*/
private applyDomTransformations;
/**
* Loads CSS content from a file path
*
* @private
* @param {string} cssPath - Path to the CSS file to load
* @returns {Promise<string>} A promise that resolves to the CSS content, or empty string on error
*/
private loadCss;
/**
* Builds a complete HTML document with head, body, and embedded styles
*
* Creates a well-formed HTML5 document with:
* - Proper DOCTYPE and meta tags
* - Responsive viewport configuration
* - Embedded CSS styles (base + custom)
* - SEO-friendly metadata
* - Print-optimized styling
*
* @private
* @param {Object} options - Configuration for building the HTML document
* @param {string} options.body - The HTML body content
* @param {string} options.css - Custom CSS to embed
* @param {string} options.title - Document title
* @param {Record<string, string>} [options.metadata] - Additional metadata for HTML head
* @returns {string} Complete HTML document as string
*/
private buildHtmlDocument;
/**
* Unescape specific structural HTML tags that were escaped in imported content
*
* Selectively unescapes certain structural tags that are needed for styling and page breaks.
*
* Tags unescaped:
* - <div class="page-break-before"></div>
* - <div class="page-break-after"></div>
* - Other div/span tags with specific classes
*
* @param html - HTML content with potentially escaped tags
* @returns HTML with structural tags unescaped
* @private
*/
private unescapeStructuralTags;
}
/**
* Singleton instance of HtmlGenerator for convenient importing
* @example
* ```typescript
* import { htmlGenerator } from './html-generator.js';
* const html = await htmlGenerator.generateHtml(content);
* ```
*/
export declare const htmlGenerator: HtmlGenerator;
export declare function _removeYamlFrontmatter(content: string): string;
export declare function _applyDomTransformations($: cheerio.CheerioAPI): void;
export declare function _buildHtmlDocument(options: {
body: string;
css: string;
title: string;
metadata?: Record<string, unknown>;
useDefaultCss?: boolean;
}): Promise<string>;
export declare function _unescapeStructuralTags(html: string): string;
//# sourceMappingURL=html-generator.d.ts.map