LegalDownMarkdown for Legal Documents
An open standard for writing contracts and legal documents in plain text. Human-readable, machine-parseable, and built for collaboration. Write once — render to PDF, DOCX, or HTML. Track every change with Git.
{{money: 50000, currency=USD}}USD 50,000.00 As set forth in Section {{ref: payment-terms}}...As set forth in Section 2… shall terminate on {{date: 2026-06-01}}shall terminate on June 1, 2026 within {{duration: 30, unit=D}}within 30 days ---
title: Mutual Non-Disclosure Agreement
legaldown: "0.2"
document_type: contract
---
# Definitions {#definitions}
"Confidential Information" {{def: confidential-info}}
means any non-public information
disclosed by one side to the other.
# Obligations {#obligations}
{{party: beta}} shall protect the
{{term: confidential-info}} using
reasonable care.The Problem with Legal Documents Today
Four problems that cost legal teams thousands of hours a year.
Trapped in Proprietary Formats
Contracts live inside Word files full of hidden formatting and binary noise. Sharing one means emailing attachments and hoping.
Numbering Breaks Constantly
Move one section and half the cross-references point somewhere else. Renumbering clauses by hand is work nobody should still be doing.
No Real Version Control
Track Changes turns a negotiation into an unreadable mess, and comparing two drafts means reading both. Nothing records who changed what.
Opaque to Automation
Binary and XML formats bury structure under formatting markup. No tool can reliably pull out a clause or a liability cap without guessing.
Edit the Contract, Watch It Render
A real document, checked by the reference validator on every keystroke. Edit the source and the contract follows.
Checked by legaldown-validator, the tool you put in CI. Real output is styled by a style template and exported to PDF or DOCX. This page renders up to 4,000 characters; the command-line tool has no limit.
What You Are Actually Writing
A LegalDown file is a YAML header followed by a Markdown body, plus a small set of constructs for what contracts need and Markdown lacks.
Headings Are Structure
# is a top-level provision, ## a subsection, down to five levels. The headings are the structure.
Stable Identifiers
{#payment-terms} after a heading assigns a permanent id. References point at the id, never the number.
Tracked Defined Terms
Declare with {{def: id}}, use with {{term: id}}. Validation proves every referenced term is defined exactly once, and links it back.
Structured Metadata
Parties, dates, governing law and document type sit in the YAML header, where any tool can read them.
The document_type field adapts the structure and metadata rules:
Contracts
Agreements between named sides — NDAs, MSAs, employment, licence, lease.
Unilateral acts
Issued by one party — notices, declarations, powers of attorney.
Collective acts
Adopted by an organisation — bylaws, internal regulations, board resolutions.
Templates Carry Their Own Logic
One file holds every variant. Answer its questions and assembly writes an ordinary document, the same bytes every time — and a valid template assembles cleanly for every valid set of answers.
questions: Declared in the header, with prompts and defaults.
{#id when=vat} Keeps or drops a whole section, item or paragraph.
{{choose: ...}} Swaps a phrase; every answer must be covered.
> [!DRAFTING] Guidance for the drafter, removed on assembly.
The LegalDown Directive Toolkit
Inline directives, written as {{directive: value}}, mark up the legal-specific parts. Open one to see what it renders to.
"Term" {{def: id}}Define a Term
The term in quotation marks, then {{def: id}}. The quotes are never rendered; an omitted id is derived from the term.
"Confidential Information" {{def: confidential-info}} means...
Confidential Information means… {{term: term-id}}Use a Defined Term
Uses a defined term anywhere, linked back to its definition.
The {{term: confidential-info}} shall be...
The Confidential Information shall be… {{ref: section-id}}Cross-Reference a Section
Resolves to the section's current number, linked. You write 'Section' yourself, so the format works in any language.
As set forth in Section {{ref: payment-terms}}...
As set forth in Section 2… {{party: name}}Reference a Party
A party declared in the frontmatter, with an optional label= for inflection.
{{party: acme}} shall deliver...
Acme shall deliver… {{side: name}}Reference a Side
The collective counterpart of {{party:}} — a whole side at once, for obligations that bind a group jointly.
The {{side: clients}} shall be jointly liable...
The Clients shall be jointly liable… {{date: YYYY-MM-DD}}Calendar Date
An unambiguous ISO 8601 date, formatted for the reader's locale.
shall terminate on {{date: 2026-06-01}}
shall terminate on June 1, 2026 {{money: amount, currency=X}}Monetary Amount
An amount with an ISO 4217 currency code, formatted locally and never rounded.
{{money: 50000, currency=USD}}
USD 50,000.00 {{duration: value, unit=U}}Time Duration
A time span with an explicit unit: S, MIN, H, D, W, MO or Y.
within {{duration: 30, unit=D}}
within 30 days {{field: value, type=t}}Custom Typed Value
A value of your own type — case numbers, invoice numbers — declared in frontmatter to validate it.
{{field: INV-2026-0042, type=invoice-id}}
INV-2026-0042 {{placeholder: id}}Fillable Placeholder
A blank to fill in — text, date, money or duration. A template's question gives it a prompt.
{{placeholder: fee, type=money, currency=EUR}}
a ruled blank, typed as money in EUR {{choose: question, a=text, b=text}}Inline Choice
In a template, a phrase picked by an answer. Every answer must be listed, so a new option cannot drop text.
interim relief from {{choose: forum, courts="a court", arbitration="an arbitrator"}}
interim relief from [a court / an arbitrator] {{attach: id}}Reference an Attachment
A schedule, exhibit or annex declared in the frontmatter, by its title.
as specified in {{attach: schedule-a}}
as specified in Schedule A {{include: path}}Include a Fragment
Splices in a fragment file: shared definitions, standard clauses.
{{include: fragments/standard-terms.lgd}}
the fragment's own text, spliced in here The Reference Validator
A standard is only as good as the tool that enforces it. legaldown-validator parses, validates and serialises LegalDown documents — and it is what checks the playground above.
Exit code 1 on any error-level diagnostic — or on any diagnostic at all under --strict — so a broken contract never reaches signature.
What It Checks
Seventy-nine of the specification's 116 rules, each at the severity the specification assigns it.
Every Finding Has a Rule Id
Each diagnostic carries the specification's stable rule id beside its severity. Suppress one check, escalate another, or gate a build on exactly the rules you care about.
Command Line and Python API
Validate a file or a whole tree from the shell, or call parse_document, validate_document and serialize_document directly — the same engine either way.
Built for CI Pipelines
JSON output for annotations and dashboards, --strict to tighten the gate, --ignore to grant one exception, and --final to refuse a document with anything left to fill in.
Validate on Every Commit
Two lines in a workflow file put every contract in the repository under continuous validation. The exit code fails the job; rule ids let you grant exceptions without switching whole checks off.
View legaldown-validator on GitHubPython 3.11+ · MIT licensed · one dependency (PyYAML) · Level 1 — Core conformance, verified against the specification's fixtures
- run: pip install legaldown-validator
- run: legaldown validate contracts/ --warnings-as-errorsLegalDown vs. Traditional Drafting
Eight things that change when a contract is plain text with explicit structure.
| Feature | Traditional | LegalDown |
|---|---|---|
| Section numbering |
Manual — breaks when you move sections
|
Automatic — always correct at render time
|
| Cross-references |
Hardcoded text — breaks silently
|
Identifier-based — validated automatically
|
| Version comparison |
Track Changes — unreliable and hard to read
|
Git diff — clear, line-by-line comparison
|
| Defined terms |
Manual bold formatting — no link to definition
|
Declared & linked — validated for consistency
|
| Formatting & style |
Embedded in document — inconsistent across versions
|
Separate style templates — always consistent output
|
| Templates |
A copy per variant — the logic lives in the drafter's head
|
Questions and conditions in the file — assembled deterministically
|
| AI analysis |
Requires parsing binary or XML formats
|
Native plain text — directly processable by any LLM
|
| Collaboration |
Email attachments — version confusion inevitable
|
Git branches — full audit trail, merge support
|
Built for AI & Automation
Traditional legal documents need expensive parsing and heuristic extraction. A LegalDown document is already structured data.
Feed Directly to LLMs
Pass a whole contract to any language model with no preprocessing — it sees structure, not formatting noise.
Structured Data Extraction
Parties, dates and governing law are declared in YAML. Parse the header and you have the data.
Clause Comparison at Scale
One set of structural rules, so liability caps or payment terms compare across a whole portfolio.
Get Started
LegalDown is an open standard. Read the specification, try the validator, and open an issue if the format does not fit the way you work.
Write
Draft in any text editor — Markdown for structure, directives for the legal parts.
Validate
Run legaldown validate. Broken references and undefined terms surface before anyone signs.
Render
Generate PDF, DOCX or HTML from a style template; numbering and references are computed.
Collaborate
Commit to Git: real diffs, real history, clean merges.