Creare una fattura professionale con Markdown

Creare documenti professionali ed eleganti come le fatture è un’esigenza comune sia per le aziende sia per i liberi professionisti. Strumenti come LaTeX e HTML sono spesso usati a questo scopo, ma possono essere complessi e scomodi da mantenere. Ecco allora Pandoc, un convertitore universale di documenti, e Markdown, un linguaggio di markup leggero. Insieme formano una soluzione semplice ma potente per creare un modello di fattura personalizzabile.

In questo articolo vediamo come creare una fattura professionale usando il Markdown di Pandoc con i fenced div e i CSS. Approfondiremo anche perché questo approccio è più facile da mantenere e più versatile rispetto a LaTeX o a file HTML completi.

Il modello di fattura

Ecco il modello di fattura che ho sviluppato con l’aiuto di ChatGPT, che funziona molto bene per questo tipo di applicazioni

File PDF

# 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>

Prompt per l’LLM:

Potrebbe essere necessario procedere in più passaggi, ma il seguente prompt può servire da guida:

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

Come funziona

Fenced div con Pandoc

I fenced div di Pandoc permettono di creare elementi a livello di blocco con classi specifiche. In questo modello abbiamo usato classi diverse per le varie sezioni, come bill-to, ship-to, items e notes. Questo approccio modulare offre la flessibilità di definire lo stile di ciascuna sezione separatamente.

Capire i fenced div in Pandoc

I fenced div fanno parte della sintassi Markdown estesa di Pandoc. Permettono di racchiudere uno o più paragrafi, titoli, elenchi o altri elementi a livello di blocco in un contenitore con una classe o un identificatore specifico. Ciò è particolarmente utile quando si vuole applicare uno stile specifico a una sezione del documento.

Sintassi

La sintassi di base di un fenced div è la seguente:

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

• :::: questi due punti segnano l’inizio e la fine del fenced div.
• class-name: sostituitelo con il nome della classe che volete assegnare al div.

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

Esempio d’uso

Ecco un esempio di come usare un fenced div per creare una sezione con una classe specifica:

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

In questo esempio al contenuto del fenced div viene assegnata la classe warning. Potete poi usare i CSS per definire lo stile di questa classe, ad esempio per colorare il testo di rosso o aggiungere un’icona di avviso.

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

Applicare più classi o ID

Potete anche applicare più classi o persino un ID a un fenced div. Ecco la sintassi:

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

• #my-id: assegna al div l’ID my-id.
• .class1 .class2: assegnano al div le classi class1 e class2.

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

Uso nel modello di fattura

Nel modello di fattura proposto, i fenced div sono stati usati per creare sezioni distinte, come bill-to, ship-to, items e notes. Usando classi diverse per queste sezioni, potete applicare stili specifici a ciascuna, semplificando la progettazione e la manutenzione del layout.

Stile CSS

Il CSS incluso definisce lo stile della fattura, con adattamenti del layout, stile dei bordi e stili specifici per la stampa. In questo modo la fattura ha un aspetto professionale ed è pronta per la stampa.

Il tag <style> incluso contiene il CSS che definisce lo stile della fattura, con adattamenti del layout, stile dei bordi e stili specifici per la stampa. Potete personalizzarlo secondo il vostro marchio o le vostre preferenze grafiche.

• Layout: le sezioni bill-to e ship-to sono affiancate. Abbiamo anche aggiunto un clearfix per la sezione items per garantire un allineamento corretto.
• Stile della tabella: la tabella delle voci ha bordi e spaziatura interna per presentare le informazioni in modo ordinato.
• Stili di stampa: la query @media print garantisce che il layout venga adattato correttamente per la stampa.

Perché scegliere Markdown invece di LaTeX o HTML completo?

Semplicità e leggibilità

• Markdown: leggibile e pulito.
• LaTeX: potente ma complesso.
• HTML completo: scomodo, con tag annidati.

Manutenibilità e flessibilità

• Markdown: facile da aggiornare, con contenuto e stile separati.
• LaTeX e HTML completo: richiedono più tempo per la manutenzione.

Facilità di conversione in altri formati

• Markdown con Pandoc: conversione in HTML e PDF senza fatica.

Conversione in HTML

Potete usare Pandoc per convertire questo file Markdown in HTML o in qualsiasi altro formato supportato da Pandoc. Ecco un semplice comando per convertire il file Markdown in HTML:

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

Conversione in PDF

Convertite il file HTML in PDF con la funzione di stampa del browser o con Pandoc:

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

Conclusione: una soluzione versatile

Scegliere Markdown con Pandoc per creare un modello di fattura offre semplicità, manutenibilità e flessibilità. Rende il processo accessibile anche a chi non è esperto di LaTeX o HTML e permette una facile conversione in vari formati, PDF compreso.

Quindi, la prossima volta che dovete preparare una fattura, provate Pandoc e Markdown. Potrebbe diventare la vostra soluzione di riferimento per creare documenti professionali e personalizzabili.

Un ringraziamento speciale ai Tokyo Builders per l’ispirazione. Buona fatturazione!