Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/petalo/legal-markdown-js

Process markdown with YAML front matter, conditional clauses, cross-references, imports, and generate professional PDFs ready to be shared.
https://github.com/petalo/legal-markdown-js

legal-documents legaltools markdown markdown-converter

Last synced: 2 months ago
JSON representation

Process markdown with YAML front matter, conditional clauses, cross-references, imports, and generate professional PDFs ready to be shared.

Awesome Lists containing this project

README 

          
# Legal Markdown JS



> A Node.js and TypeScript implementation of the original Ruby

> [LegalMarkdown](https://github.com/compleatang/legal-markdown) project. Legal

> Markdown JS processes legal markdown documents with advanced features and

> PDF/HTML exports.



Process markdown with YAML front matter, conditional clauses

`[text]{condition}`, cross-references `|reference|`, mixins `{{variable}}`,

imports `@import`, and generate professional PDFs ready to be shared.



![Legal Markdown JS Example](docs/legal-markdown-js-example.png)



## Table of Contents



- [Installation](#installation)

- [Quick Start](#quick-start)

- [Key Features](#key-features)

- [Documentation](#documentation)

- [Testing](#testing)

- [Contributing](#contributing)

- [License](#license)



## Installation



```bash

npm install legal-markdown-js

```



After installation, you'll have access to these commands:



- **`legal-md`** - Standard command-line interface with options and flags

- **`legal-md-ui`** - Interactive CLI with guided prompts and smart defaults

- **`legal-md-setup`** - Configuration setup script for easy environment setup

- **`legal-md-playground`** - Local playground server for testing and

  exploration



## 🚀 Try it Online



**[Live Playground](https://petalo.github.io/legal-markdown-js/)** - Try Legal

Markdown JS directly in your browser with live examples and real-time

processing.



### Local Playground



You can also run the playground locally for offline use or testing:



```bash

# Start local playground server (when installed globally)

legal-md-playground



# Or with custom port

legal-md-playground --port=3000



# Or if installed locally in a project

npm run web:serve

```



The playground provides the same interactive experience as the online version,

including real-time processing, syntax highlighting, and example templates.



## Quick Start



### Initial Setup (Optional)



For the best experience, especially if you're new to Legal Markdown JS, run the

setup script to configure your environment:



```bash

# Configure paths and directories (when installed globally)

legal-md-setup



# Or if installed locally in a project

npm run setup-config

```



This creates a personalized configuration file that the tool will automatically

find and use.



### Command Line Usage



#### Standard CLI



```bash

# Basic document processing

legal-md input.md output.md



# Generate PDF with highlighting

legal-md document.md --pdf --highlight



# Process with custom CSS and archive source

legal-md document.md --html --css styles.css --archive-source



# Archive to custom directory

legal-md document.md --archive-source ./processed

```



#### Interactive CLI



For a guided, user-friendly experience, use the interactive CLI:



```bash

# Launch interactive mode

legal-md-ui

```



The interactive CLI provides:



- **📁 Smart file discovery**: Automatically scans your input directory for

  supported files (`.md`, `.markdown`, `.rst`, `.tex`, `.latex`, `.txt`)

- **🎯 Multiple output formats**: Select any combination of PDF, HTML, Markdown,

  and metadata export

- **⚙️ Conditional options**: Processing options adapt based on your selected

  formats

- **🎨 CSS selection**: Choose from available stylesheets or proceed without

  custom styling

- **📦 Source archiving**: Configure automatic archiving of source files after

  successful processing

- **📋 Configuration summary**: Review all settings before processing

- **✅ Clear results**: See exactly which files were generated



### Programmatic Usage



```typescript

import {

  processLegalMarkdown,

  processLegalMarkdownAsync,

} from 'legal-markdown-js';



// Synchronous processing

const result = processLegalMarkdown(content, {

  basePath: './documents',

  exportMetadata: true,

  exportFormat: 'json',

});



// Asynchronous processing with remark pipeline (recommended)

const asyncResult = await processLegalMarkdownAsync(content, {

  basePath: './documents',

  exportMetadata: true,

  exportFormat: 'json',

  enableFieldTracking: true,

});



console.log(asyncResult.content);

console.log(asyncResult.metadata);

console.log(asyncResult.fieldReport); // Enhanced field tracking

```



## Key Features



### Core Compatibility



All original Legal Markdown features are fully implemented:



- **File Formats**: Markdown, ASCII, reStructuredText, LaTeX

- **YAML Front Matter**: Complete parsing with all standard fields

- **Headers & Numbering**: Full hierarchical numbering system (`l.`, `ll.`,

  `lll.`)

- **Optional Clauses**: Boolean, equality, and logical operations

  (`[text]{condition}`)

- **Cross-References**: Internal section references using (`|reference|`) syntax

- **Partial Imports**: File inclusion with path resolution (`@import`)

- **Metadata Export**: YAML and JSON export with custom paths



### Node.js Enhancements



Additional features available only in the Node.js version:



- **Interactive CLI**: User-friendly guided interface with smart file discovery

  and configuration management

- **Mixins System**: Template substitution and helpers with `{{variable}}`

  syntax

- **AST-Based Processing**: Modern AST-based mixin processing to prevent text

  contamination (v2.4.0+)

- **Pipeline Architecture**: Configurable step-based processing pipeline with

  dependency management and performance monitoring (v2.4.0+)

- **PDF Generation**: Professional PDF output with styling and field

  highlighting

- **HTML Generation**: Custom HTML output with CSS support

- **Template Loops**: Array iteration with `{{#items}}...{{/items}}` syntax

- **Helper Functions**: Date, number, and string formatting helpers

- **Force Commands**: Document-driven configuration with embedded CLI options

- **Batch Processing**: Multi-file processing with concurrency control

- **Field Tracking**: Enhanced field tracking with proper categorization for

  document review

- **Source File Archiving**: Automatic archiving of source files after

  successful processing with conflict resolution



## Architecture & Performance



### Modern Pipeline System (v2.4.0+)



Legal Markdown JS features a completely rewritten processing pipeline that

provides:



- **Step-Based Architecture**: Configurable processing steps with dependency

  management

- **AST-Based Processing**: Modern AST parsing for mixin processing to prevent

  text contamination

- **Performance Monitoring**: Built-in step profiling and performance metrics

- **Error Recovery**: Graceful error handling and comprehensive logging

- **Field Tracking**: Enhanced field tracking with proper status categorization



#### Processing Order



The new pipeline ensures correct processing order to prevent conflicts:



1. **YAML Front Matter** - Parse document metadata

2. **Import Processing** - Handle file imports and inclusions

3. **Optional Clauses** - Process conditional text blocks

4. **Cross-References** - Resolve internal document references

5. **Template Loops** - Expand array iterations first

6. **AST Mixin Processing** - Process variables and helpers (avoids loop

   conflicts)

7. **Header Processing** - Apply numbering and formatting

8. **Field Tracking** - Apply highlighting and generate reports



#### API Usage



```typescript

// Use the remark-based async API for best performance

const result = await processLegalMarkdownAsync(content, options);



// Comprehensive error handling and validation

// Full remark-based processing for all documents

```



## Documentation



### User Documentation



- **[Getting Started](docs/getting_started.md)** - Installation and setup guide

- **[CLI Reference](docs/cli_reference.md)** - Complete command-line interface

  documentation

- **[Features Guide](docs/features/README.md)** - All features, helpers, and

  advanced usage

- **[Headers & Numbering](docs/features/headers-numbering.md)** - Hierarchical

  numbering system guide

- **[CSS Classes Reference](docs/CSS-CLASSES.md)** - CSS classes for styling and

  document review

- **[Features Overview](docs/FEATURES.md)** - Complete feature implementation

  status and testing coverage



### Developer Documentation



- **[Architecture](docs/architecture.md)** - Complete system architecture and

  design patterns

- **[Contributing Guide](docs/development/contributing.md)** - Development

  workflow, standards, and contribution guidelines

- **[Helper Functions](docs/helpers/README.md)** - Complete reference for

  template helpers and functions

- **[Development Guide](docs/development/development-guide.md)** - Complete

  developer setup and workflow

- **[Release Process](docs/development/release-process.md)** - Versioning and

  release procedures

- **[Scripts Reference](docs/development/scripts-reference.md)** - Available npm

  scripts and commands

- **[API Documentation](docs/api/)** - Auto-generated TypeScript API docs



## Testing



```bash

# Run all tests

npm test



# Run specific test types

npm run test:unit

npm run test:integration

npm run test:e2e



# Run with coverage

npm run test:coverage

```



- **Unit Tests**: Test individual components in isolation

- **Integration Tests**: Test complete workflows and feature combinations

- **E2E Tests**: Test CLI interface and full application behavior

- **Path Validation Tests**: Test environment configuration and error handling



## Configuration



Legal Markdown JS supports environment-based configuration for customizing file

paths and directories.



### Quick Setup (Recommended)



For easy configuration setup, especially for non-technical users:



```bash

# Run the setup script (when installed globally)

legal-md-setup



# Or if installed locally in a project

npm run setup-config

```



This script will:



- Create a configuration directory at `~/.config/legal-markdown-js/`

- Copy the configuration template with helpful comments

- Provide clear instructions on how to customize your paths

- Show you exactly where to edit your settings



### Manual Configuration



If you prefer manual setup, create a `.env` file in one of these locations (in

order of precedence):



1. **Current working directory**: `./.env`

2. **Your home directory**: `~/.env`

3. **Config directory**: `~/.config/legal-markdown-js/.env`



```bash

# Copy the example configuration

cp .env.example .env



# Edit the configuration

nano .env

```



### Path Configuration Examples



```bash

# Custom asset organization

IMAGES_DIR=assets/media

STYLES_DIR=assets/css



# Separate project structure

DEFAULT_INPUT_DIR=documents/source

DEFAULT_OUTPUT_DIR=documents/generated

ARCHIVE_DIR=documents/archive



# Absolute paths (useful for CI/CD)

IMAGES_DIR=/var/lib/legal-markdown/images

DEFAULT_OUTPUT_DIR=/var/lib/legal-markdown/output

ARCHIVE_DIR=/var/lib/legal-markdown/archive

```



### Using Custom Paths in Code



```typescript

import { PATHS, RESOLVED_PATHS } from 'legal-markdown-js';



// Access configured paths

console.log(PATHS.STYLES_DIR); // Relative path from .env

console.log(RESOLVED_PATHS.STYLES_DIR); // Absolute resolved path

```



## Contributing



We welcome contributions! Please see our

[Contributing Guide](docs/development/contributing.md) for:



- Development setup and workflow

- Coding standards and best practices

- Testing requirements

- Pull request process



### Quick Start for Contributors



1. Fork the repository

2. Create a feature branch (`git checkout -b feature/amazing-feature`)

3. Follow the development guidelines

4. Run the test suite (`npm test`)

5. Submit a Pull Request



## License



MIT License - see [LICENSE](LICENSE) file for details.



## Acknowledgments



- Original [LegalMarkdown](https://github.com/compleatang/legal-markdown)

  project by Casey Kuhlman

- The legal tech community for inspiration and feedback