{"id":29945646,"url":"https://github.com/petalo/legal-markdown-js","last_synced_at":"2026-03-07T16:05:42.873Z","repository":{"id":304981033,"uuid":"1021498589","full_name":"petalo/legal-markdown-js","owner":"petalo","description":"Process markdown with YAML front matter, conditional clauses, cross-references, imports, and generate professional PDFs ready to be shared.","archived":false,"fork":false,"pushed_at":"2025-08-02T21:11:29.000Z","size":3082,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-02T22:24:47.801Z","etag":null,"topics":["legal-documents","legaltools","markdown","markdown-converter"],"latest_commit_sha":null,"homepage":"https://petalo.github.io/legal-markdown-js/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petalo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit-ci.json","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-17T13:41:33.000Z","updated_at":"2025-08-02T21:11:32.000Z","dependencies_parsed_at":"2025-07-17T19:37:36.177Z","dependency_job_id":"1c19d940-2d2c-49ae-bf4e-96ac091069b7","html_url":"https://github.com/petalo/legal-markdown-js","commit_stats":null,"previous_names":["petalo/legal-markdown-js"],"tags_count":42,"template":false,"template_full_name":null,"purl":"pkg:github/petalo/legal-markdown-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalo%2Flegal-markdown-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalo%2Flegal-markdown-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalo%2Flegal-markdown-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalo%2Flegal-markdown-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petalo","download_url":"https://codeload.github.com/petalo/legal-markdown-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petalo%2Flegal-markdown-js/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268470581,"owners_count":24255375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["legal-documents","legaltools","markdown","markdown-converter"],"created_at":"2025-08-03T05:01:55.151Z","updated_at":"2026-03-07T16:05:42.814Z","avatar_url":"https://github.com/petalo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Legal Markdown JS\n\n\u003e A Node.js and TypeScript implementation of the original Ruby\n\u003e [LegalMarkdown](https://github.com/compleatang/legal-markdown) project. Legal\n\u003e Markdown JS processes legal markdown documents with advanced features and\n\u003e PDF/HTML exports.\n\nProcess markdown with YAML front matter, conditional clauses\n`[text]{condition}`, cross-references `|reference|`, mixins `{{variable}}`,\nimports `@import`, and generate professional PDFs ready to be shared.\n\n![Legal Markdown JS Example](docs/legal-markdown-js-example.png)\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Key Features](#key-features)\n- [Documentation](#documentation)\n- [Testing](#testing)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n```bash\nnpm install legal-markdown-js\n```\n\nAfter installation, you'll have access to these commands:\n\n- **`legal-md`** - Standard command-line interface with options and flags\n- **`legal-md-ui`** - Interactive CLI with guided prompts and smart defaults\n- **`legal-md-setup`** - Configuration setup script for easy environment setup\n- **`legal-md-playground`** - Local playground server for testing and\n  exploration\n\n## 🚀 Try it Online\n\n**[Live Playground](https://petalo.github.io/legal-markdown-js/)** - Try Legal\nMarkdown JS directly in your browser with live examples and real-time\nprocessing.\n\n### Local Playground\n\nYou can also run the playground locally for offline use or testing:\n\n```bash\n# Start local playground server (when installed globally)\nlegal-md-playground\n\n# Or with custom port\nlegal-md-playground --port=3000\n\n# Or if installed locally in a project\nnpm run web:serve\n```\n\nThe playground provides the same interactive experience as the online version,\nincluding real-time processing, syntax highlighting, and example templates.\n\n## Quick Start\n\n### Initial Setup (Optional)\n\nFor the best experience, especially if you're new to Legal Markdown JS, run the\nsetup script to configure your environment:\n\n```bash\n# Configure paths and directories (when installed globally)\nlegal-md-setup\n\n# Or if installed locally in a project\nnpm run setup-config\n```\n\nThis creates a personalized configuration file that the tool will automatically\nfind and use.\n\n### Command Line Usage\n\n#### Standard CLI\n\n```bash\n# Basic document processing\nlegal-md input.md output.md\n\n# Generate PDF with highlighting\nlegal-md document.md --pdf --highlight\n\n# Process with custom CSS and archive source\nlegal-md document.md --html --css styles.css --archive-source\n\n# Archive to custom directory\nlegal-md document.md --archive-source ./processed\n```\n\n#### Interactive CLI\n\nFor a guided, user-friendly experience, use the interactive CLI:\n\n```bash\n# Launch interactive mode\nlegal-md-ui\n```\n\nThe interactive CLI provides:\n\n- **📁 Smart file discovery**: Automatically scans your input directory for\n  supported files (`.md`, `.markdown`, `.rst`, `.tex`, `.latex`, `.txt`)\n- **🎯 Multiple output formats**: Select any combination of PDF, HTML, Markdown,\n  and metadata export\n- **⚙️ Conditional options**: Processing options adapt based on your selected\n  formats\n- **🎨 CSS selection**: Choose from available stylesheets or proceed without\n  custom styling\n- **📦 Source archiving**: Configure automatic archiving of source files after\n  successful processing\n- **📋 Configuration summary**: Review all settings before processing\n- **✅ Clear results**: See exactly which files were generated\n\n### Programmatic Usage\n\n```typescript\nimport {\n  processLegalMarkdown,\n  processLegalMarkdownAsync,\n} from 'legal-markdown-js';\n\n// Synchronous processing\nconst result = processLegalMarkdown(content, {\n  basePath: './documents',\n  exportMetadata: true,\n  exportFormat: 'json',\n});\n\n// Asynchronous processing with remark pipeline (recommended)\nconst asyncResult = await processLegalMarkdownAsync(content, {\n  basePath: './documents',\n  exportMetadata: true,\n  exportFormat: 'json',\n  enableFieldTracking: true,\n});\n\nconsole.log(asyncResult.content);\nconsole.log(asyncResult.metadata);\nconsole.log(asyncResult.fieldReport); // Enhanced field tracking\n```\n\n## Key Features\n\n### Core Compatibility\n\nAll original Legal Markdown features are fully implemented:\n\n- **File Formats**: Markdown, ASCII, reStructuredText, LaTeX\n- **YAML Front Matter**: Complete parsing with all standard fields\n- **Headers \u0026 Numbering**: Full hierarchical numbering system (`l.`, `ll.`,\n  `lll.`)\n- **Optional Clauses**: Boolean, equality, and logical operations\n  (`[text]{condition}`)\n- **Cross-References**: Internal section references using (`|reference|`) syntax\n- **Partial Imports**: File inclusion with path resolution (`@import`)\n- **Metadata Export**: YAML and JSON export with custom paths\n\n### Node.js Enhancements\n\nAdditional features available only in the Node.js version:\n\n- **Interactive CLI**: User-friendly guided interface with smart file discovery\n  and configuration management\n- **Mixins System**: Template substitution and helpers with `{{variable}}`\n  syntax\n- **AST-Based Processing**: Modern AST-based mixin processing to prevent text\n  contamination (v2.4.0+)\n- **Pipeline Architecture**: Configurable step-based processing pipeline with\n  dependency management and performance monitoring (v2.4.0+)\n- **PDF Generation**: Professional PDF output with styling and field\n  highlighting\n- **HTML Generation**: Custom HTML output with CSS support\n- **Template Loops**: Array iteration with `{{#items}}...{{/items}}` syntax\n- **Helper Functions**: Date, number, and string formatting helpers\n- **Force Commands**: Document-driven configuration with embedded CLI options\n- **Batch Processing**: Multi-file processing with concurrency control\n- **Field Tracking**: Enhanced field tracking with proper categorization for\n  document review\n- **Source File Archiving**: Automatic archiving of source files after\n  successful processing with conflict resolution\n\n## Architecture \u0026 Performance\n\n### Modern Pipeline System (v2.4.0+)\n\nLegal Markdown JS features a completely rewritten processing pipeline that\nprovides:\n\n- **Step-Based Architecture**: Configurable processing steps with dependency\n  management\n- **AST-Based Processing**: Modern AST parsing for mixin processing to prevent\n  text contamination\n- **Performance Monitoring**: Built-in step profiling and performance metrics\n- **Error Recovery**: Graceful error handling and comprehensive logging\n- **Field Tracking**: Enhanced field tracking with proper status categorization\n\n#### Processing Order\n\nThe new pipeline ensures correct processing order to prevent conflicts:\n\n1. **YAML Front Matter** - Parse document metadata\n2. **Import Processing** - Handle file imports and inclusions\n3. **Optional Clauses** - Process conditional text blocks\n4. **Cross-References** - Resolve internal document references\n5. **Template Loops** - Expand array iterations first\n6. **AST Mixin Processing** - Process variables and helpers (avoids loop\n   conflicts)\n7. **Header Processing** - Apply numbering and formatting\n8. **Field Tracking** - Apply highlighting and generate reports\n\n#### API Usage\n\n```typescript\n// Use the remark-based async API for best performance\nconst result = await processLegalMarkdownAsync(content, options);\n\n// Comprehensive error handling and validation\n// Full remark-based processing for all documents\n```\n\n## Documentation\n\n### User Documentation\n\n- **[Getting Started](docs/getting_started.md)** - Installation and setup guide\n- **[CLI Reference](docs/cli_reference.md)** - Complete command-line interface\n  documentation\n- **[Features Guide](docs/features/README.md)** - All features, helpers, and\n  advanced usage\n- **[Headers \u0026 Numbering](docs/features/headers-numbering.md)** - Hierarchical\n  numbering system guide\n- **[CSS Classes Reference](docs/CSS-CLASSES.md)** - CSS classes for styling and\n  document review\n- **[Features Overview](docs/FEATURES.md)** - Complete feature implementation\n  status and testing coverage\n\n### Developer Documentation\n\n- **[Architecture](docs/architecture.md)** - Complete system architecture and\n  design patterns\n- **[Contributing Guide](docs/development/contributing.md)** - Development\n  workflow, standards, and contribution guidelines\n- **[Helper Functions](docs/helpers/README.md)** - Complete reference for\n  template helpers and functions\n- **[Development Guide](docs/development/development-guide.md)** - Complete\n  developer setup and workflow\n- **[Release Process](docs/development/release-process.md)** - Versioning and\n  release procedures\n- **[Scripts Reference](docs/development/scripts-reference.md)** - Available npm\n  scripts and commands\n- **[API Documentation](docs/api/)** - Auto-generated TypeScript API docs\n\n## Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test types\nnpm run test:unit\nnpm run test:integration\nnpm run test:e2e\n\n# Run with coverage\nnpm run test:coverage\n```\n\n- **Unit Tests**: Test individual components in isolation\n- **Integration Tests**: Test complete workflows and feature combinations\n- **E2E Tests**: Test CLI interface and full application behavior\n- **Path Validation Tests**: Test environment configuration and error handling\n\n## Configuration\n\nLegal Markdown JS supports environment-based configuration for customizing file\npaths and directories.\n\n### Quick Setup (Recommended)\n\nFor easy configuration setup, especially for non-technical users:\n\n```bash\n# Run the setup script (when installed globally)\nlegal-md-setup\n\n# Or if installed locally in a project\nnpm run setup-config\n```\n\nThis script will:\n\n- Create a configuration directory at `~/.config/legal-markdown-js/`\n- Copy the configuration template with helpful comments\n- Provide clear instructions on how to customize your paths\n- Show you exactly where to edit your settings\n\n### Manual Configuration\n\nIf you prefer manual setup, create a `.env` file in one of these locations (in\norder of precedence):\n\n1. **Current working directory**: `./.env`\n2. **Your home directory**: `~/.env`\n3. **Config directory**: `~/.config/legal-markdown-js/.env`\n\n```bash\n# Copy the example configuration\ncp .env.example .env\n\n# Edit the configuration\nnano .env\n```\n\n### Path Configuration Examples\n\n```bash\n# Custom asset organization\nIMAGES_DIR=assets/media\nSTYLES_DIR=assets/css\n\n# Separate project structure\nDEFAULT_INPUT_DIR=documents/source\nDEFAULT_OUTPUT_DIR=documents/generated\nARCHIVE_DIR=documents/archive\n\n# Absolute paths (useful for CI/CD)\nIMAGES_DIR=/var/lib/legal-markdown/images\nDEFAULT_OUTPUT_DIR=/var/lib/legal-markdown/output\nARCHIVE_DIR=/var/lib/legal-markdown/archive\n```\n\n### Using Custom Paths in Code\n\n```typescript\nimport { PATHS, RESOLVED_PATHS } from 'legal-markdown-js';\n\n// Access configured paths\nconsole.log(PATHS.STYLES_DIR); // Relative path from .env\nconsole.log(RESOLVED_PATHS.STYLES_DIR); // Absolute resolved path\n```\n\n## Contributing\n\nWe welcome contributions! Please see our\n[Contributing Guide](docs/development/contributing.md) for:\n\n- Development setup and workflow\n- Coding standards and best practices\n- Testing requirements\n- Pull request process\n\n### Quick Start for Contributors\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Follow the development guidelines\n4. Run the test suite (`npm test`)\n5. Submit a Pull Request\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Original [LegalMarkdown](https://github.com/compleatang/legal-markdown)\n  project by Casey Kuhlman\n- The legal tech community for inspiration and feedback\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetalo%2Flegal-markdown-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetalo%2Flegal-markdown-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetalo%2Flegal-markdown-js/lists"}