Billdown

Billdown is a fast, lightweight CLI tool that generates financial documents (Invoices, Quotations, Receipts) from Markdown templates and JSON data.

Unlike simple text replacers, Billdown acts as a logic engine: it calculates line totals, applies taxes, formats currency, and supports batch processing out of the box.

Features

• Smart Calculations: Automatically calculates subtotals, taxes (percent or fixed), and grand totals.
• Batch Processing: Generates hundreds of PDFs from a single JSON array.
• Markdown Templates: Design your documents using standard Markdown and HTML.
• Configurable: Global settings for currency symbols, date formats, and tax rules.
• Safe Output: Automatically versions files with timestamps to prevent accidental overwrites (unless --force is used).
• Cross-Platform: Compiles to a single binary for Windows, Linux, and macOS.

Installation

Prerequisites

• Go 1.20+ (only required to build).
• Google Chrome or Microsoft Edge installed (used for headless PDF rendering).

Build

Run the provided build script for your platform to generate the binary in the dist/v<version> folder.

Windows:

.\build.bat <version>

Linux/macOS:

chmod +x build.sh
./build.sh <version>

Quickstart

1. Generate a Sample: Create a default template and see the output.

   billdown sample invoice

   This creates default_invoice.md and generates a sample PDF.

2. Create Configuration: Create a billdown.json file in the root directory.

   {
     "currency_symbol": "RM",
     "date_format": "02 Jan 2006",
     "taxes": [
       { "name": "SST", "type": "percent", "rate": 0.06 }
     ]
   }

3. Prepare Data: Create a data.json file.

   [
     {
       "customer_name": "Acme Corp",
       "items": [
         { "desc": "Consulting", "qty": 10, "price": 150 }
       ]
     }
   ]

4. Generate PDF:

   billdown invoice data.json

   The output will be saved in the exports/ directory.

CLI Usage

# General Syntax
billdown <type> <data_file> [flags]

# Generate Quotation
billdown quotation data.json

# Generate Invoice with custom template
billdown invoice data.json --template custom_layout.md

# Generate Receipt and overwrite existing files
billdown receipt data.json --force

# Generate Receipt and change output directory
billdown receipt data.json --output /receipts

# Generate Receipt with custom template and change output directory and silently
billdown receipt data.json -t custom_layout.md -o /receipts --silent

# Check Version
billdown version

# Show help
billdown help

Flags

• -t, --template: Path to a custom Markdown file.

• -o, --output: Output directory for generated PDFs (default "exports")

• --force: Overwrite existing files in the exports folder.

• --silent: Suppress all output messages.

• --debug: Enable verbose logging for troubleshooting.

Template System

Templates are Markdown files (.md). You can use HTML for advanced styling (tables, alignment).

Variable Namespaces

Billdown exposes data to the template in three namespaces:

1. User Data (Flattened): Directly access fields from your data.json.

   • Example: {{customer_name}}

2. System Data (system.): Values calculated by the engine.

   • {{system.current_date}}: Today's date (formatted per config).

   • {{system.subtotal}}: Sum of all items.

   • {{system.taxes}}: Array of calculated taxes.

   • {{system.grand_total}}: Final total including tax.

   • {{system.index}}: Item row number (inside loops).

   • {{system.total}}: Line total (qty * price).

3. Configuration (config.): Read-only access to global settings.

   • {{config.currency_symbol}}

Example Template

<p><img src="/images/logo.png" style="height:80px;"></p>

**Date:** {{system.current_date}}
**To:** {{customer_name}}

| # | Item | Qty | Price | Total |
| :-: | :--- | :-: | :-: | :-: |
{{#each items}}
| {{system.index}} | {{desc}} | {{qty}} | {{price}} | {{system.total}} |
{{/each}}

**Grand Total: {{system.grand_total}}**

Note: Always leave a blank line between HTML tags and Markdown text to ensure proper rendering.

Data Structure (data.json)

Billdown accepts either a single Object {} or an Array [].

[
  {
    "filename": "ClientA",
    "customer_name": "Client A",
    "items": [
      { "desc": "Service 1", "qty": 1, "price": 1000.00 }
    ]
  },
  {
    "filename": "ClientB_USD",
    "customer_name": "Client B",
    "config": {
      "currency_symbol": "USD"
    },
    "items": [
      { "desc": "Service 1", "qty": 1, "price": 500.00 }
    ]
  }
]

• filename: Output filename (e.g., ClientA_Receipt.pdf).

• config override: You can override global billdown.json settings per document (as seen in Client B above).

Project Structure

• billdown.exe: The main executable.

• billdown.json: Global configuration.

• data.json: Main data for PDFs generation.

• default_<type>.md: Default templates (created automatically if missing).

• images/: Store local assets (logos) here.

Contributing

Contributions are welcome! If you have ideas for new features or bug fixes, please open a pull request.

Credits

• Atif Mustaffa

License

This project is licensed under the MIT License - see the LICENSE file for details.