Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adzialocha/document-generator
Generate your .pdf invoices, letters, documents, etc. with templates based on YAML, HTML & SCSS
https://github.com/adzialocha/document-generator
document-generator invoice-generator nunjucks pdf scss yaml
Last synced: 2 months ago
JSON representation
Generate your .pdf invoices, letters, documents, etc. with templates based on YAML, HTML & SCSS
- Host: GitHub
- URL: https://github.com/adzialocha/document-generator
- Owner: adzialocha
- License: mit
- Created: 2018-07-02T15:22:34.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-02-24T11:29:16.000Z (10 months ago)
- Last Synced: 2024-09-26T20:45:55.711Z (3 months ago)
- Topics: document-generator, invoice-generator, nunjucks, pdf, scss, yaml
- Language: JavaScript
- Homepage:
- Size: 188 KB
- Stars: 23
- Watchers: 4
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# document-generator
Generate your .pdf invoices, letters, documents, etc. with templates based on [YAML](https://yaml.org/), [HTML](https://dev.w3.org/html5/html-author/) & [SCSS](https://sass-lang.com).
## Features
* Separates the document content from its form
* Templates and contents can easily be combined with version control systems
* Reads the actual content in simple YAML syntax
* Generates documents layouted and styled via HTML and SCSS (with variables, @import statements, etc.)
* Offers filters, inheritance, loops etc. in HTML templates via [Nunjucks](https://mozilla.github.io/nunjucks/)
* Organizes multiple templates and *flavours* for template variants (for example different languages of one document)
* Generates .pdf files via [puppeteer](https://pptr.dev/)
## Install
It is recommended to install `document-generator` globally via `npm`:
$ npm install -g document-generator
## Usage
```
Usage: document-generator [options]
Generate your .pdf invoices, letters, documents, etc. with templates based on YAML, HTML & SCSS
Options:
-V, --version output the version number
-s, --source path to source folder, defaults to "~/.document-templates" (default: "~/.document-templates")
-o, --output output .pdf file path, defaults to "./-.pdf"
-n, --name add an optional name to the generated pdf file name. Works only when default output name is being used
-t, --template template name, defaults to "invoice" (default: "invoice")
-f, --flavour flavour name, defaults to "default" (default: "default")
-h, --help output usage information
```
## Example
This is a small tutorial on how to maintain your own document templates and how to use `document-generator`.
1. By default `document-generator` looks into `~/.document-templates/` for your templates (change this via the `--source` option). Create a folder named `invoice` here:
$ mkdir -p ~/.document-templates/invoice
2. Create a `template.yaml` file in this folder to define basic options which will be passed on to [puppeteer](https://pptr.dev/) for .pdf generation:
$ touch template.yaml
*.document-templates/invoice/template.yaml*
```yaml
format: A4
margin:
top: 30
right: 60
bottom: 30
left: 60
```
3. Now create a `template.html` file to define the layout of the document. You can use [Nunjucks](https://mozilla.github.io/nunjucks/) template language to work with variables, inheritance, loops etc.:
$ touch template.html
*.document-templates/invoice/template.html*
```html
{{ flavour.title }}
- {{ item.description }} - {{ item.price }}
{% for item in items %}
{% endfor %}
```
4. As you see above, we use variables in our template to render dynamic data. Every document template consists of one or more *flavours*, think of them as a variation of your document. Flavours come in handy if you want to generate your invoices in different languages for example.
Create a directory named `flavours` in your template folder:
$ mkdir flavours
$ touch flavours/default.yaml
Create a flavour file in this folder named `default.yaml`, it will be the standard flavour the generator picks as long as you didn't define another flavour via the `--flavour` option. Since we used already one flavour variable named `title` in the HTML template, we define it here with YAML syntax:
*.document-templates/invoice/flavours/default.yaml*
```yaml
title: Invoice
```
Let's create an alternative flavour (just for fun) and name it `de.yaml` to have the option to generate a German invoice:
$ touch de.yaml
*.document-templates/invoice/flavours/de.yaml*
```yaml
title: Rechnung
```
5. To style the document we create a `styles` folder in the template folder with a `template.scss` file inside:
$ mkdir styles
$ touch styles/template.scss
Use CSS or SCSS sytax now to style your layout. You can also separate your styles into separate files etc., we will only have a single, simple file for now:
*.document-templates/invoice/styles/template.scss*
```scss
$blue: #00f;
h1 {
color: $blue;
}
```
6. We are done with creating our invoice template! The file structure should be the following now:
```yaml
invoice
├── flavours
│ ├── default.yaml
│ └── de.yaml
├── styles
│ ├── template.scss
├── template.html
└── template.yaml
```
7. Create the actual `my-invoice.yaml` to generate a .pdf file.
$ touch ~/my-invoice.yaml
So far we only declared one variable named `items` in our template, lets fill it with content:
```yaml
items:
- description: Doing something
price: 10
- description: Doing something else
price: 90
```
8. Finally run `document-generator` to make a .pdf! The program uses the `invoice` template by default:
$ document-generator my-invoice.yaml
To generate the German invoice, we would add the `--flavour` option:
$ document-generator my-invoice.yaml --flavour de
To use another template, you could adress it via:
$ document-generator a-serious-letter.yaml --flavour official --template letter
## License
`MIT`