Hi HN! I'm sharing legal-markdown-js, a TypeScript port of an abandoned 2011 Ruby gem that solves a surprisingly complex problem: writing legal documents that don't break when you edit them.

The Problem: Legal documents have intricate numbering schemes (1.1.1, (a)(i), etc.) and cross-references. Change one section and you might need to renumber 50+ references manually. Plus there's tons of repetitive boilerplate clauses scattered across documents. Lawyers often avoid restructuring documents because it's too error-prone.

The Solution: Write contracts in Markdown with tons of helper functions: auto-numbering, variables, conditional blocks, cross-references, and imports.

Example

    ---
    party1: "ACME Corp"
    party2: "{{client_name}}"
    jurisdiction: "California"
    ---

    # Software License Agreement

    l. This Agreement is between {{party1}} and {{party2}}.
    l. License Grant
    ll. Restrictions
    lll. No reverse engineering
    lll. See section @[License Grant] for details

    {{#if enterprise}}
    l. Enterprise Features
    ll. Priority support included
    {{/if}}

    @import "clauses/standard_termination.md"

The l. markers become proper legal numbering, variables expand ({{client_name}}), conditional blocks show/hide content ({{#if enterprise}}), cross-references update automatically (@[License Grant]), and imports (@import) let you reuse boilerplate clauses.

Why I Built This

I stopped programming to build startups, became a corporate PM, and now I'm starting a fund. I wanted control over the legal documents we share with LPs and portfolio companies – tired of paying lawyers for simple template changes, but most importantly frustrated with losing version history in Word docs.

Scratching this itch became my late-night learning vehicle for modern development practices. What started as "I'll just port this Ruby gem" turned into a deep dive into TypeScript, testing frameworks, and the entire modern JS ecosystem.

Technical Details

- Full TypeScript with strict typing - Extensive test coverage - ESM-first with CommonJS fallback - Remark/Unified integration for extensibility - CLI + programmatic API - Full processing pipeline with multiple format outputs including PDF with highlights

The original Ruby gem was solid but abandoned. The JavaScript ecosystem deserved a maintained version, especially with legal tech growing rapidly.

Who This Helps

- Humans and legal professionals tired of Word's auto-numbering disasters - Legal tech companies building document automation - Anyone generating contracts programmatically - Developers who need to template complex documents

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

Playground: https://petalo.github.io/legal-markdown-js/

Original Ruby Project: https://github.com/compleatang/legal-markdown