Document Directive¶

Overview¶

The document directive links an external file (receipt, statement, contract) to an account at a specific date. It creates a paper trail connecting financial records to supporting documentation.

Syntax¶

document = date WHITESPACE "document" WHITESPACE account WHITESPACE path
           [WHITESPACE tags_links]*
           (NEWLINE metadata)*

path = string

Components¶

Date¶

The date the document is associated with (typically the date on the document).

Account¶

The account the document relates to.

Path¶

A string containing the file path to the document. Can be: - Relative path (resolved from the ledger file's directory) - Absolute path

Tags and Links¶

Optional tags and links to categorize or connect documents.

Examples¶

Basic Document¶

2024-01-01 open Assets:Checking USD

2024-01-15 document Assets:Checking "documents/2024/01/bank-statement.pdf"

Receipt Attachment¶

2024-01-15 document Expenses:Office "receipts/2024/01/staples-receipt.jpg"
  amount: "125.50 USD"
  vendor: "Staples"

With Tags¶

2024-01-15 document Assets:Checking "statements/2024-01.pdf" #statement #monthly

With Links¶

2024-01-15 document Liabilities:Mortgage "contracts/mortgage-agreement.pdf" ^mortgage-2024

Multiple Documents¶

; Monthly statements
2024-01-01 document Assets:Checking "statements/2024-01-checking.pdf"
2024-02-01 document Assets:Checking "statements/2024-02-checking.pdf"
2024-03-01 document Assets:Checking "statements/2024-03-checking.pdf"

Path Resolution¶

Relative Paths¶

Relative paths are resolved from the directory containing the ledger file:

/home/user/finances/
├── ledger.beancount
├── documents/
│   └── 2024/
│       └── receipt.pdf

; In ledger.beancount
2024-01-15 document Expenses:Food "documents/2024/receipt.pdf"
; Resolves to: /home/user/finances/documents/2024/receipt.pdf

Absolute Paths¶

Absolute paths are used as-is:

2024-01-15 document Assets:Checking "/mnt/archive/statements/2024-01.pdf"

Document Root¶

A document root can be configured:

option "documents" "/home/user/finances/docs"

; Paths resolve relative to document root
2024-01-15 document Assets:Checking "statements/2024-01.pdf"
; Resolves to: /home/user/finances/docs/statements/2024-01.pdf

Automatic Document Discovery¶

Some implementations scan directories for documents matching patterns:

option "documents" "/home/user/Documents/Financial"

; Automatically discovers:
; /home/user/Documents/Financial/Assets/Checking/2024-01-15.statement.pdf
; Creates: 2024-01-15 document Assets:Checking "Assets/Checking/2024-01-15.statement.pdf"

Directory structure convention:

documents/
├── Assets/
│   └── Checking/
│       ├── 2024-01-15.statement.pdf
│       └── 2024-02-15.statement.pdf
├── Expenses/
│   └── Office/
│       └── 2024-01-20.receipt.staples.jpg

Validation¶

The following conditions may produce errors:

Condition	Error Type
Account not opened	`ValidationError`

File Existence Check¶

Document file existence is checked at load time. Missing files produce a DocumentError:

DocumentError: File does not exist: "/path/to/missing.pdf"

This check is automatic and cannot be disabled via options. All referenced document files should exist.

Common Document Types¶

Type	Extension	Use Case
PDF	`.pdf`	Statements, contracts, invoices
Image	`.jpg`, `.png`	Receipts, photos of documents
Scan	`.tiff`	High-quality scans
Text	`.txt`	Notes, text exports

Metadata¶

Common metadata keys:

2024-01-15 document Assets:Checking "statement.pdf"
  type: "bank-statement"
  period: "2024-01"
  pages: 3
  file-hash: "sha256:abc123..."

Linking to Transactions¶

Documents can be linked to related transactions:

2024-01-15 * "Office Supplies" ^purchase-001
  Expenses:Office  125.50 USD
  Assets:Checking

2024-01-15 document Expenses:Office "receipts/staples.pdf" ^purchase-001

Or using transaction metadata:

2024-01-15 * "Office Supplies"
  document: "receipts/staples.pdf"
  Expenses:Office  125.50 USD
  Assets:Checking

Use Cases¶

Tax Documentation¶

; Keep all tax-relevant documents
2024-12-31 document Income:Salary "tax/2024/w2.pdf" #tax-2024
2024-12-31 document Assets:Brokerage "tax/2024/1099-div.pdf" #tax-2024
2024-12-31 document Assets:Brokerage "tax/2024/1099-b.pdf" #tax-2024

Contract Archive¶

2024-01-01 document Liabilities:Mortgage "contracts/mortgage-note.pdf"
  signed-date: 2024-01-01
  term: "30 years"
  rate: "6.5%"

Receipt Organization¶

2024-01-15 document Expenses:Business:Travel "receipts/2024/flight-nyc.pdf"
2024-01-16 document Expenses:Business:Travel "receipts/2024/hotel-nyc.pdf"
2024-01-17 document Expenses:Business:Meals "receipts/2024/dinner-client.jpg"

Implementation Notes¶

Store document references indexed by account and date
Validate file existence (configurable)
Support relative and absolute paths
Enable document discovery from configured directories
Documents don't affect financial calculations