llms.txt

# Legal Markdown JS

TypeScript/Node.js implementation of LegalMarkdown for processing legal document templates written in Markdown with YAML frontmatter.

## Overview

- Converts Legal Markdown into processed Markdown, HTML, PDF, DOCX, and metadata exports.
- Targets legal and structured business documents that need automatic numbering, templating, conditional clauses, imports, and review highlighting.
- Exposes both a CLI (`legal-md`, `legal-md-ui`, `legal-md-playground`) and a programmatic TypeScript API.

## Core Capabilities

- Parse YAML frontmatter and expose values to templates.
- Replace variables and evaluate helper functions inside `{{ ... }}` expressions.
- Process legal headers such as `l.`, `ll.`, `lll.` with automatic numbering and indentation.
- Render conditional content with bracket syntax and Handlebars-style blocks.
- Resolve cross-references between sections.
- Import partial Markdown files with recursive processing and frontmatter merging.
- Generate HTML, PDF, and DOCX outputs, including highlighted review variants.
- Track substituted fields and logic branches for document review/debugging.
- Export merged metadata as YAML or JSON.
- Support batch and interactive CLI workflows.

## Key Concepts

- Frontmatter: documents typically start with YAML metadata between `---` markers.
- Variables and helpers: use `{{field}}`, nested paths like `{{client.name}}`, and helper calls such as `{{formatCurrency(amount, currency)}}`.
- Headers: legal hierarchy uses repeated `l` markers (`l.` to `lllllllll.`) for up to 9 levels.
- Conditional clauses:
  - `[content]{condition}`
  - `{{#if condition}}...{{else}}...{{/if}}`
  - `{{#variable}}...{{/variable}}`
- Imports: use `@import path/to/file.md` or quoted paths like `@import "clauses/standard terms.md"`.
- Cross-references: use pipe-based references such as `|reference|` to link sections after numbering is resolved.
- Frontmatter merging: imported files can contribute metadata; the source document keeps precedence on conflicts.
- Field tracking: HTML/PDF/DOCX flows can annotate substituted fields and winning logic branches for review output.

## CLI / API

- CLI basic usage: `legal-md [options] [input] [output]`
- Common CLI outputs:
  - `legal-md input.md output.md`
  - `legal-md input.md --html`
  - `legal-md input.md --pdf`
  - `legal-md input.md --docx`
  - `cat input.md | legal-md --stdin --stdout`
- Important CLI flags:
  - Processing: `--no-headers`, `--no-clauses`, `--no-references`, `--no-imports`, `--no-mixins`
  - Review/debug: `--enable-field-tracking`, `--ast-field-tracking`, `--logic-branch-highlighting`, `--debug`
  - Output: `--html`, `--pdf`, `--docx`, `--highlight`, `--export-yaml`, `--export-json`
  - PDF backend: `--pdf-connector auto|puppeteer|system-chrome|weasyprint`
- Main library exports:
  - `processLegalMarkdown(content, options)`
  - `generateHtml(content, options)`
  - `generatePdf(content, outputPath, options)`
  - `generatePdfVersions(content, outputPath, options)`
  - `generateDocx(content, outputPath, options)`
  - `generateDocxVersions(content, outputPath, options)`

## Documentation

- Docs index: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/README.md
- Getting started: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/getting_started.md
- CLI reference: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/cli_reference.md
- Features index: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/README.md
- YAML frontmatter: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/yaml-frontmatter.md
- Headers and numbering: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/headers-numbering.md
- Cross-references: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/cross-references.md
- Optional clauses: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/optional-clauses.md
- Conditionals: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/conditionals.md
- Partial imports: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/partial-imports.md
- Variables and mixins: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/mixins-variables.md
- Template loops: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/template-loops.md
- Date processing: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/date-processing.md
- Force commands: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/features/force-commands.md
- Helpers index: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/helpers/README.md
- Date helpers: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/helpers/date-helpers.md
- Number helpers: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/helpers/number-helpers.md
- String helpers: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/helpers/string-helpers.md
- Math helpers: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/helpers/math-helpers.md
- Output formats index: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/output/README.md
- PDF generation: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/output/pdf-generation.md
- HTML generation: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/output/html-generation.md
- DOCX generation: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/output/docx-generation.md
- Field highlighting: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/output/field-highlighting.md
- CSS classes: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/output/css-classes.md
- Advanced topics: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/advanced/README.md
- Configuration: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/advanced/configuration.md
- Batch processing: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/advanced/batch-processing.md
- Best practices: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/advanced/best-practices.md
- Processing pipeline: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/processing/README.md
- Field tracking internals: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/processing/field-tracking.md
- Architecture overview: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/ARCHITECTURE.md
- Security notes: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/reference/security.md
- Troubleshooting: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/docs/reference/troubleshooting.md

## Examples

- Examples index: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/README.md
- Basic processing walkthrough: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/basic-processing/simple-document/README.md
- Basic input document: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/basic-processing/simple-document/input.md
- YAML frontmatter example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/basic-processing/yaml-frontmatter/README.md
- CLI usage examples: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/integration/cli-usage/README.md
- Cross-references example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/cross-references/basic-references/README.md
- Optional clauses example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/optional-clauses/conditional-content/README.md
- Boolean logic example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/optional-clauses/boolean-logic/README.md
- Helper functions example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/mixins/helper-functions/README.md
- Template loops example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/mixins/template-loops/README.md
- Partial imports example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/imports/partial-imports/README.md
- Frontmatter merging example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/imports/frontmatter-merging/README.md
- PDF generation example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/output-formats/pdf-generation/README.md
- Metadata export example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/output-formats/metadata-export/README.md
- Advanced NDA example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/advanced/complex-nda/README.md
- Advanced lease example: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/examples/advanced/office-lease-complete/README.md

## Source Code

- Package metadata: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/package.json
- Public API entrypoint: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/index.ts
- CLI entrypoint: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/cli/main.ts
- CLI service: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/cli/service.ts
- Interactive CLI: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/cli/interactive/service.ts
- Core pipeline directory: https://github.com/petalo/legal-markdown-js/tree/main/src/core/pipeline
- Remark processor: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/extensions/remark/legal-markdown-processor.ts
- Remark plugins directory: https://github.com/petalo/legal-markdown-js/tree/main/src/plugins/remark
- Generators directory: https://github.com/petalo/legal-markdown-js/tree/main/src/extensions/generators
- PDF connector resolver: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/extensions/generators/pdf-connectors/resolver.ts
- Types: https://raw.githubusercontent.com/petalo/legal-markdown-js/main/src/types.ts
- Web playground app: https://github.com/petalo/legal-markdown-js/tree/main/src/web

## Notes for AI Agents

- Prefer the docs in `docs/features/` and `docs/helpers/` for syntax details; the README is only the top-level overview.
- For CLI behavior, treat `docs/cli_reference.md` as the canonical option list.
- For template syntax, expect a mix of LegalMarkdown-specific constructs (`l.`, `@import`, bracket clauses) and Handlebars-style constructs (`{{field}}`, `{{#if}}`).
- For output generation, HTML/PDF/DOCX may enable field tracking automatically even when clean Markdown output does not.
- For import behavior, remember that metadata from imported files merges into the main document, but the source document wins on conflicts.
- For source-level reasoning, the processing path centers on the remark pipeline and plugins under `src/extensions/remark/` and `src/plugins/remark/`.