{"id":15018089,"url":"https://github.com/adzialocha/document-generator","last_synced_at":"2025-10-23T15:30:50.174Z","repository":{"id":57214301,"uuid":"139460604","full_name":"adzialocha/document-generator","owner":"adzialocha","description":"Generate your .pdf invoices, letters, documents, etc. with templates based on YAML, HTML \u0026 SCSS","archived":false,"fork":false,"pushed_at":"2024-02-24T11:29:16.000Z","size":192,"stargazers_count":23,"open_issues_count":1,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-01-30T19:11:18.312Z","etag":null,"topics":["document-generator","invoice-generator","nunjucks","pdf","scss","yaml"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adzialocha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-02T15:22:34.000Z","updated_at":"2024-07-31T06:39:21.000Z","dependencies_parsed_at":"2024-09-16T12:49:49.239Z","dependency_job_id":null,"html_url":"https://github.com/adzialocha/document-generator","commit_stats":{"total_commits":21,"total_committers":3,"mean_commits":7.0,"dds":"0.47619047619047616","last_synced_commit":"2a36328b5befc0ddc530a6085b0a4c325b8e3acb"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fdocument-generator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fdocument-generator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fdocument-generator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adzialocha%2Fdocument-generator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adzialocha","download_url":"https://codeload.github.com/adzialocha/document-generator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237843932,"owners_count":19375230,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["document-generator","invoice-generator","nunjucks","pdf","scss","yaml"],"created_at":"2024-09-24T19:51:26.221Z","updated_at":"2025-10-23T15:30:49.841Z","avatar_url":"https://github.com/adzialocha.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# document-generator\n\nGenerate your .pdf invoices, letters, documents, etc. with templates based on [YAML](https://yaml.org/), [HTML](https://dev.w3.org/html5/html-author/) \u0026 [SCSS](https://sass-lang.com).\n\n## Features\n\n* Separates the document content from its form\n* Templates and contents can easily be combined with version control systems\n* Reads the actual content in simple YAML syntax\n* Generates documents layouted and styled via HTML and SCSS (with variables, @import statements, etc.)\n* Offers filters, inheritance, loops etc. in HTML templates via [Nunjucks](https://mozilla.github.io/nunjucks/)\n* Organizes multiple templates and *flavours* for template variants (for example different languages of one document)\n* Generates .pdf files via [puppeteer](https://pptr.dev/)\n\n## Install\n\nIt is recommended to install `document-generator` globally via `npm`:\n\n    $ npm install -g document-generator\n\n## Usage\n\n```\nUsage: document-generator [options] \u003cfile\u003e\n\nGenerate your .pdf invoices, letters, documents, etc. with templates based on YAML, HTML \u0026 SCSS\n\nOptions:\n  -V, --version          output the version number\n  -s, --source \u003cpath\u003e    path to source folder, defaults to \"~/.document-templates\" (default: \"~/.document-templates\")\n  -o, --output \u003cpath\u003e    output .pdf file path, defaults to \"./\u003cYYYYMMDD\u003e-\u003ctemplateName\u003e.pdf\"\n  -n, --name \u003cname\u003e      add an optional name to the generated pdf file name. Works only when default output name is being used\n  -t, --template \u003cname\u003e  template name, defaults to \"invoice\" (default: \"invoice\")\n  -f, --flavour \u003cname\u003e   flavour name, defaults to \"default\" (default: \"default\")\n  -h, --help             output usage information\n```\n\n## Example\n\nThis is a small tutorial on how to maintain your own document templates and how to use `document-generator`.\n\n1. By default `document-generator` looks into `~/.document-templates/` for your templates (change this via the `--source` option). Create a folder named `invoice` here:\n\n        $ mkdir -p ~/.document-templates/invoice\n\n2. 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:\n\n        $ touch template.yaml\n\n    *.document-templates/invoice/template.yaml*\n\n    ```yaml\n    format: A4\n    margin:\n        top: 30\n        right: 60\n        bottom: 30\n        left: 60\n    ```\n\n3. 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.:\n\n        $ touch template.html\n\n    *.document-templates/invoice/template.html*\n\n    ```html\n    \u003chtml\u003e\n      \u003chead\u003e\n        \u003cmeta charset=\"utf-8\"\u003e\n      \u003c/head\u003e\n      \u003cbody\u003e\n        \u003cheader\u003e\n          \u003ch1\u003e{{ flavour.title }}\u003c/h1\u003e\n        \u003c/header\u003e\n        \u003cmain\u003e\n          \u003cul\u003e\n            {% for item in items %}\n              \u003cli\u003e{{ item.description }} - {{ item.price }}\u003c/li\u003e\n            {% endfor %}\n          \u003c/ul\u003e\n        \u003c/main\u003e\n      \u003c/body\u003e\n    \u003c/html\u003e\n    ```\n\n4. 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.\n\n    Create a directory named `flavours` in your template folder:\n\n        $ mkdir flavours\n        $ touch flavours/default.yaml\n\n    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:\n\n    *.document-templates/invoice/flavours/default.yaml*\n    \n    ```yaml\n    title: Invoice\n    ```\n\n    Let's create an alternative flavour (just for fun) and name it `de.yaml` to have the option to generate a German invoice:\n    \n        $ touch de.yaml\n\n    *.document-templates/invoice/flavours/de.yaml*\n\n    ```yaml\n    title: Rechnung\n    ```\n\n5. To style the document we create a `styles` folder in the template folder with a `template.scss` file inside:\n\n        $ mkdir styles\n        $ touch styles/template.scss\n\n    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:\n\n    *.document-templates/invoice/styles/template.scss*\n\n    ```scss\n    $blue: #00f;\n\n    h1 {\n      color: $blue;\n    }\n    ```\n\n6. We are done with creating our invoice template! The file structure should be the following now:\n\n    ```yaml\n    invoice\n    ├── flavours\n    │   ├── default.yaml\n    │   └── de.yaml\n    ├── styles\n    │   ├── template.scss\n    ├── template.html\n    └── template.yaml\n    ```\n\n7. Create the actual `my-invoice.yaml` to generate a .pdf file.\n\n        $ touch ~/my-invoice.yaml\n\n    So far we only declared one variable named `items` in our template, lets fill it with content:\n\n    ```yaml\n    items:\n        - description: Doing something\n          price: 10\n        - description: Doing something else\n          price: 90\n    ```\n\n8. Finally run `document-generator` to make a .pdf! The program uses the `invoice` template by default:\n\n        $ document-generator my-invoice.yaml\n\n    To generate the German invoice, we would add the `--flavour` option:\n\n        $ document-generator my-invoice.yaml --flavour de\n\n    To use another template, you could adress it via:\n\n        $ document-generator a-serious-letter.yaml --flavour official --template letter\n\n## License\n\n`MIT`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzialocha%2Fdocument-generator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadzialocha%2Fdocument-generator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadzialocha%2Fdocument-generator/lists"}