mrzool / invoice-boilerplate

Simple automated LaTeX invoicing system

Invoice Boilerplate

Simple automated LaTeX invoicing system for freelancers.

Intro

Built along the lines of cv-boilerplate and letter-boilerplate, this boilerplate contains the bare minimum to produce a professional-looking invoice with the least possible effort.

The invoice content lives in details.yml and it's structured like so:

invoice-nr: 2015-11-04
author: Max Mustermann
city: Musterstadt
from:
- Musterstraße 37
- 12345 Musterstadt
to:
- Erika Mustermann
- Musterallee 1
- 12345 Musterstadt
- Germany
VAT: 20
service:
- description: The first service provided
  price: 450.00
- description: And another one, with a list of details
  price: 245.00
  details:
    - Some more detailed explanation
    - of the service provided
    - Looking good
- description: The last service provided
  price: 245.00

When running make, Pandoc starts iterating on the YAML file, populates template.tex with your data, and pipes the result to XeTeX. XeTeX deals with the typesetting and compiles a PDF ready to be printed/faxed/emailed and archived (see the output).

The math gets handled internally by LaTeX through the spreadtab package, Excel-style (mad props to clemens on TeX SE for helping me out with this). You just need to provide a VAT rate and your prices, the boilerplate takes care of the rest.

Unless you plan to edit the template, no particular LaTeX knowledge is required to use this boilerplate. If you need your invoice in a language other than English, finding the relevant strings in template.tex and translating them to your language should be easy enough.

Dependencies

1. LaTeX with the following extra packages: fontspec geometry ragged2e spreadtab fp xstring arydshln hhline titlesec enumitem xunicode xltxtra hyperref polyglossia wallpaper footmisc
2. Pandoc, the universal document converter.

I highly recommend TinyTeX as LaTeX distribution. All additional packages can be installed with tlmgr as needed.

Getting started

1. Open details.yml with your text editor and fill it with your details, the invoice recipient's details, services/prices, and the desired settings.
2. Run make to compile the PDF.

Some countries require invoices to be signed. If a file named signature.pdf is present in the directory, the boilerplate will automatically print it after the closing note as a final touch. Follow this method to import your own signature.

Note: this template needs to be compiled with XeTeX.

Note for Windows users

Although I didn't test it, you can probably use this on Windows, too. Both Pandoc and LaTeX can be installed on Windows and you should be able to run makefiles on Windows through Cygwin. If that's too much hassle, this command should do the trick in Powershell:

pandoc details.yml -o output.pdf --template=template.tex --pdf-engine=xelatex

Available settings

• VAT: Your VAT rate.
• currency: Your currency code (USD, EUR...)
• commasep: Set to true to use a comma as decimal separator. This is for display purposes only—remember to always use a dot to set the prices in your YAML file.
• lang: Sets the main language through the polyglossia package. This is important for proper hyphenation and date format. Use IETF language tags format, as that is what Pandoc expects.
• seriffont: Used for the heading and the sender address. Hoefler Text is the default, but every font installed on your system should work out of the box thanks to XeTeX.
• sansfont: Used to render the recipient address, the table and the closing note. Defaults to Helvetica Neue.
• fontsize: Possible values here are 10pt, 11pt and 12pt.
• geometry: A string that sets the margins through geometry. Read this to learn how this package works.
• closingnote: This gets printed after the table as a closing note. Use it to provide your bank details and a thank you message.
• letterhead: include custom letterhead in the PDF (see below).

Custom letterhead

If you have already designed your own letterhead and want to use it with this template, including it should be easy enough. Set the letterhead option to true to activate the wallpaper package in the template. wallpaper will look for a file named letterhead.pdf in the project root folder and print it on the PDF before compiling the document. Change the fonts to match the ones in your letterhead, adjust the margins with geometry and you should be all set.

Recommended readings

• Typesetting Automation, my article about this project with in-depth instructions and some suggestions for an ideal workflow.
• Grids of Numbers Recommendations on Butterick's Practical Typography
• Multichannel Text Processing by iA
• Why Microsoft Word must Die by Charlie Stross
• Word Processors: Stupid and Inefficient by Allin Cottrell
• Proprietary Binary Data Formats: Just Say No! by Sam Steingold
• The Beauty of LaTeX by Dario Taraborelli

Resources

• TinyTeX is a lightweight, cross-platform, portable, and easy-to-maintain LaTeX distribution based on TeX Live.
• Refer to pandoc's documentation to learn more about how templates work.
• If you're not familiar with the YAML syntax, here's a good overview.
• If you want to edit the template but LaTeX scares you, these docs put together by ShareLaTeX cover most of the basics and are surprisingly kind to the beginner.
• Odds are your question already has an answer on TeX Stack Exchange. Also, pretty friendly crowd in there.
• Need to fax that invoice? Check out Phaxio and learn how to send your faxes from the command line with a simple API call.

See also

• cv-boilerplate — Easing the process of building and maintaining a CV using LaTeX
• letter-boilerplate — Typeset your important letters without leaving your text editor

License

GPL

invoice-boilerplate's Issues

Add optional signature

Hi. It would be useful to have a signature, optionally, in the invoice. I've proposed a pull request here that changes the template, the yaml file, and adds documentation about it in the readme: #21 Please do consider it.

It's --latex-engine, not --pdf-engine

As is, I get the following error:

pandoc details.yml -o output.pdf --template=template.tex --pdf-engine=xelatex pandoc: unrecognized option --pdf-engine=xelatex'
Try pandoc --help for more information.
makefile:6: recipe for target 'output.pdf' failed
make: *** [output.pdf] Error 2
`

If replace "pdf" with "latex" in FLAGS = --pdf-engine=xelatex in makefile, it works as intended.

Maths and `spreadtab` package

Hello,

Is there any option to include new taxes a part from VAT through the spreadtab package?

Thanks in advance.

Exceeding Parameter Stack

Getting this error after running the application as normally.

How to split long tables by a page break?

I have written an invoice with several items and each item has details.

The table gets very long, so that the first page of the PDF file only contains the letter header, the second page contains the table and the third page contains the closing note.

What do I need to change to get page breaks within the table, so that my invoice fits on two pages and the first page doesn't look empty?

I tried using tblr and longtblr, but I ran into \noalign issues.

fonnts issue

Error producing PDF.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
!
! fontspec error: "font-not-found"
!
! The font "Hoefler Text" cannot be found.
!
! See the fontspec documentation for further information.
!
! For immediate help type H .
!...............................................

l.26 ...Common}, Numbers={OldStyle}]{Hoefler Text}

makefile:6: recipe for target 'output.pdf' failed
make: *** [output.pdf] Error 43

YAML not recognized, defaulting to Markdown

When I run make, I get the following warning:

pandoc details.yml -o output.pdf --template=template.tex --pdf-engine=xelatex
[WARNING] Could not deduce format from file extension .yml
  Defaulting to markdown

That doesn't seem right, IMO. We can't treat YAML as Markdown, can we?

Fonts download links

To compile the default invoice (on Windows 10), we need fonts:

Hoefler Text: https://fontsgeek.com/fonts/Hoefler-Text-Regular

Helvetica Neue: https://fontsgeek.com/helvetica-neue-font

Perhaps the download links can be added in the Readme.

UPN stack is empty errors (invoice)

I am getting the following error when I run make (invoice template):

! FP error: UPN stack is empty!.
\FP@errmessage #1->\errmessage {FP error: #1!}

l.138 \end{spreadtab}

pandoc: Error producing PDF from TeX source
makefile:2: recipe for target 'output.pdf' failed
make: *** [output.pdf] Error 43

System info as follows;

XeTeX 3.14159265-2.6-0.99992 (TeX Live 2015/Debian)
kpathsea version 6.2.1
Copyright 2015 SIL International, Jonathan Kew and Khaled Hosny.
There is NO warranty.  Redistribution of this software is
covered by the terms of both the XeTeX copyright and
the Lesser GNU General Public License.
For more information about these matters, see the file
named COPYING and the XeTeX source.
Primary author of XeTeX: Jonathan Kew.
Compiled with ICU version 55.1; using 55.1
Compiled with zlib version 1.2.8; using 1.2.8
Compiled with FreeType2 version 2.5.5; using 2.5.5
Compiled with Graphite2 version 1.3.3; using 1.3.3
Compiled with HarfBuzz version 1.0.1; using 1.0.1
Compiled with libpng version 1.6.17; using 1.6.17
Compiled with poppler version 0.32.0
Compiled with fontconfig version 2.11.0; using 2.11.0

Paragraph ended before \ST@left@ii was complete.

A nice template, that worked fine till some time ago, but I assume that either a pandoc or a latex package update broke it(?). When I run it as is, I get:

pandoc details.yml -o output.pdf --template=template.tex --pdf-engine=xelatex
[WARNING] Could not deduce format from file extension .yml
  Defaulting to markdown
[WARNING] Invalid 'lang' value 'english'.
  Use an IETF language tag like 'en-US'.

After correcting the language code, I get another error:

[WARNING] Could not deduce format from file extension .yml
  Defaulting to markdown
Error producing PDF.
! Paragraph ended before \ST@left@ii was complete.
<to be read again>
                   \par
l.135

make: *** [output.pdf] Error 43

Error 43 with \setmainlanguage

I get the following error and I don't know what I'm doing wrong. I'm just trying to compile the default invoice

Error producing PDF.
! Argument of \str_uppercase:n has an extra }.
<inserted text>
                \par
l.61 \setmainlanguage{}

make: *** [makefile:6: output.pdf] Error 43

I wonder a bit why it says line 61, because \setmainlanguage is on line 69 in template.tex