Custom Templates

[tobis72]

Hi, I installed InvoiceShelf via Portainer—it's cool software that I'd really like to use. Unfortunately, I don't understand how to create a custom template for my PDF invoices. The explanation at https://docs.invoiceshelf.com/guide/custom-templates.html isn't clear to me.
Is there perhaps a more detailed guide available? I created a .blade.php file, and it does show up in the list of options, but what should the file's content look like? Is there an example?

Thanks a lot for your help.

[pradipNP]

You don't need to write the file from scratch — there's a command that clones a built-in design for you, and that clone is the example you're looking for.

Let the generator write the first version

docker compose exec invoiceshelf php artisan make:template my-template

If you started the container from Portainer rather than compose, open Containers → invoiceshelf → Console (/bin/sh) and run php artisan make:template my-template there.

It asks whether you want an invoice or an estimate, copies the first built-in design of that type, rewrites the copy's @include lines to point at your own partials, and writes a preview image. You end up with a complete, working template that already renders — then you edit it instead of guessing at structure. Add --type=estimate to skip the prompt.

That's the bit the docs page doesn't spell out: a hand-created .blade.php shows up in the picker because any file in that directory is offered, whether or not it contains anything useful. The generator is what gives you real content.

If you'd rather read an example first

The three built-in invoice designs are in the repo:

• resources/views/app/pdf/invoice/invoice1.blade.php (also invoice2, invoice3)
• resources/views/app/pdf/invoice/partials/table.blade.php — the line-items table

Estimates are the same layout under .../pdf/estimate/. They're ordinary Blade files: an HTML document with inline <style>, so if you can write HTML and CSS you can edit them.

Variables you can use

Each template is rendered with the document's data already shared in:

$invoice (or $estimate), $customFields, $company_address, $shipping_address, $billing_address, $notes, $logo, $taxes

Two includes worth keeping

@include('pdf_templates::invoice.partials.table')
@include("app.pdf.partials.fonts")

The first is the line-items table. Careful here: that partial is written once, the first time you create a custom invoice template, and every later custom invoice template includes the same file. Editing it changes the table in all of them. If you want one template with a different table, copy the partial to a new name and point that template's @include at the copy.

The second pulls in the @font-face rules from whatever you've installed under Settings → Font Packages. Drop it and the PDF falls back to the renderer's default font, which usually bites you on accented characters.

Iterating without regenerating a PDF each time

Append ?preview=true to the document's PDF URL:

/invoices/pdf/{hash}?preview=true

That renders the template as plain HTML in the browser, so you get your browser's dev tools for the CSS instead of squinting at a regenerated PDF.

Two things that catch people on Docker

The path has an app/ segment. Templates belong in storage/app/templates/pdf/invoice/ — older versions of the docs said storage/templates/pdf/, and a file there is silently never found. Since yours already appears in the picker, you've got this right, but it's the usual cause of "my template doesn't show up".

Make sure storage/ is on a volume. Templates live outside the application code specifically so they survive upgrades, but that only holds if the directory is on a persisted volume rather than inside the container's writable layer. Worth checking in Portainer before you invest hours in a design — recreating the container on a new image tag would otherwise take it with it.

Also drop a .png next to your .blade.php with the same base name, or your template's tile in the picker renders blank.