Crafting a Professional Invoice with Markdown

Creating professional and elegant documents like invoices is a common necessity for businesses and freelancers alike. While tools like LaTeX and HTML are often used for this purpose, they can be complex and cumbersome to maintain. Enter Pandoc, a universal document converter, and Markdown, a lightweight markup language. Together, they form a simple yet powerful solution for crafting a customizable invoice template.

In this blog post, we'll explore how to create a professional invoice using Pandoc's Markdown with fenced divs and CSS. We'll also delve into why this approach is more maintainable and versatile compared to LaTeX or full HTML files.

The Invoice Template

Here's the invoice template I've developed with assistance from ChatGPT, which works very well for these kind of applications

PDF File

# Invoice

**Invoice Number:** INV-0001  
**Date:** YYYY-MM-DD  
**Due Date:** YYYY-MM-DD

::: bill-to
## Bill To

**Name:** Customer Name  
**Address:** Street Address  
**City:** City  
**State:** State  
**ZIP:** Postal Code  
**Country:** Country  
**Email:** email@example.com  
**Phone:** +00-000-0000
:::

::: ship-to
## Ship To

**Name:** Recipient Name  
**Address:** Street Address  
**City:** City  
**State:** State  
**ZIP:** Postal Code  
**Country:** Country
:::

::: items
## Items

| Description       | Quantity | Unit Price | Total      |
|-------------------|----------|------------|------------|
| Item 1            | 5        | $10.00     | $50.00     |
| Item 2            | 2        | $20.00     | $40.00     |
| Item 3            | 1        | $30.00     | $30.00     |
| **Subtotal**      |          |            | **$120.00**|
| **Tax**           |          |            | **$12.00** |
| **Total**         |          |            | **$132.00**|
:::

::: notes
## Notes

- Payment is due within 30 days from the date of the invoice.
- Please make checks payable to [Your Company Name].
- If you have any questions concerning this invoice, contact [Your Contact Information].
:::

---

Thank you for your business!

[Your Company Name]  
[Your Street Address]  
[Your City, State, ZIP]  
[Your Phone Number]  
[Your Email Address]  
[Your Website]

<style>
  body {
    font-family: Arial, sans-serif;
  }

  .section {
    margin-bottom: 20px;
  }

  .bill-to, .ship-to {
    display: inline-block;
    width: 48%;
  }

  .bill-to {
    float: left;
  }

  .ship-to {
    float: right;
  }

  .items::before {
    content: "";
    clear: both;
    display: table;
  }

  .items {
    margin-top: 10px;
  }

  .items table {
    width: 100%;
    border-collapse: collapse;
  }

  .items th, .items td {
    border: 1px solid #000;
    padding: 5px;
  }

  .notes {
    font-style: italic;
  }

  @media print {
    .bill-to, .ship-to {
      width: 45%;
    }
  }
</style>

LLM prompt:

A multistep approach might be needed but the following prompt can be used as a guide:

"Create html invoice with css that can be printed, but only output markdown with pandoc fenced_divs and also output the css."

How It Works

Fenced Divs with Pandoc

Fenced divs in Pandoc allow you to create block-level elements with specific classes. In this template, we've used different classes for various sections like bill-to, ship-to, items, and notes. This modular approach provides flexibility in styling these sections separately.

Understanding Fenced Divs in Pandoc

Fenced divs are part of Pandoc's extended Markdown syntax. They enable you to wrap one or more paragraphs, headers, lists, or other block-level elements in a container with a specific class or identifier. This can be particularly useful when you want to apply specific styling to a section of your document.

Syntax

The basic syntax for a fenced div is as follows:

::: class-name
Content inside the fenced div
:::

• :::: These colons mark the beginning and end of the fenced div.
• class-name: Replace this with the desired class name that you want to assign to the div.

<div class="class-name">
  <p>Content inside the fenced div</p>
</div>

Example Usage

Here's an example of how you might use a fenced div to create a section with a specific class:

::: warning
## Warning!
This section contains important information.
:::

In this example, the content inside the fenced div is given the class warning. You can then use CSS to style this class, perhaps to make the text red or add a warning icon.

<div class="warning">
  <h2>Warning!</h2>
  <p>This section contains important information.</p>
</div>

Applying Multiple Classes or IDs

You can also apply multiple classes or even an ID to a fenced div. Here's the syntax:

::: {#my-id .class1 .class2}
Content inside the fenced div
:::

• #my-id: This assigns an ID of my-id to the div.
• .class1 .class2: These assign the classes class1 and class2 to the div.

<div id="my-id" class="class1 class2">
  <p>Content inside the fenced div</p>
</div>

Use in the Invoice Template

In the provided invoice template, fenced divs were used to create distinct sections, such as bill-to, ship-to, items, and notes. By using different classes for these sections, you can apply specific styles to each, making it easier to design and maintain the layout.

CSS Styling

The included CSS styles the invoice, including layout adjustments, border styling, and print-specific styles. This ensures the invoice looks professional and is ready for printing.

The included <style> tag contains CSS that styles the invoice, including layout adjustments, border styling, and print-specific styles. You can customize this as per your branding or design preferences.

• Layout: The bill-to and ship-to sections are displayed side-by-side. We've also added a clear fix for the items section to ensure proper alignment.
• Table Styling: The items table is styled with borders and padding to present the information neatly.
• Print Styles: The @media print query ensures that the layout is adjusted appropriately for printing.

Why Choose Markdown over LaTeX or Full HTML?

Simplicity and Readability

• Markdown: Human-readable and clean.
• LaTeX: Powerful but complex.
• Full HTML: Cumbersome with nested tags.

Maintainability and Flexibility

• Markdown: Easy to update with a separation of content and style.
• LaTeX and Full HTML: More time-consuming to maintain.

Ease of Conversion to Other Formats

• Markdown with Pandoc: Effortless conversion to HTML and PDF.

Converting to HTML

You can use Pandoc to convert this markdown file to HTML or any other format supported by Pandoc. Here's a simple command to convert the markdown file to HTML:

pandoc -s your-invoice.md -o your-invoice.html

Conversion to PDF

Convert the HTML file into a PDF using a browser's print function or Pandoc:

pandoc your-invoice.html -o your-invoice.pdf

Conclusion: A Versatile Solution

Choosing Markdown with Pandoc for creating an invoice template offers simplicity, maintainability, and flexibility. It makes the process accessible, even to non-experts in LaTeX or HTML, and provides an easy conversion to various formats, including PDF.

So, the next time you're in need of crafting an invoice, give Pandoc and Markdown a try. It might just become your go-to solution for creating professional and customizable documents.

Special Thanks to the Tokyo Builders for the inspiration. Happy Invoicing!