{"id":50592794,"url":"https://github.com/webnium/yipt","last_synced_at":"2026-06-05T11:35:01.910Z","repository":{"id":57403802,"uuid":"93151632","full_name":"webnium/yipt","owner":"webnium","description":"Yipt: Yipt is PDF Template","archived":false,"fork":false,"pushed_at":"2018-07-18T22:20:04.000Z","size":43,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2026-06-05T11:35:00.379Z","etag":null,"topics":["javascript","nodejs-library","pdf-generation","pdfkit","typescript","typescript-library"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/webnium.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}},"created_at":"2017-06-02T09:46:38.000Z","updated_at":"2018-03-03T10:38:20.000Z","dependencies_parsed_at":"2022-08-26T01:23:06.034Z","dependency_job_id":null,"html_url":"https://github.com/webnium/yipt","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/webnium/yipt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webnium%2Fyipt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webnium%2Fyipt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webnium%2Fyipt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webnium%2Fyipt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/webnium","download_url":"https://codeload.github.com/webnium/yipt/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/webnium%2Fyipt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33939227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["javascript","nodejs-library","pdf-generation","pdfkit","typescript","typescript-library"],"created_at":"2026-06-05T11:35:00.926Z","updated_at":"2026-06-05T11:35:01.904Z","avatar_url":"https://github.com/webnium.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Yipt: Yipt is PDF Template\n\nYipt is a YAML based template engine generates PDF document.\n\nYipt uses [PDFKit](http://pdfkit.org/) for PDF generation and [JSONata](http://jsonata.org/) for template variables.\n\n## Install\n\n```bash\nnpm i yipt\n```\n\n## Usage\n\n### CLI\n\n```bash\nyipt [options] \u003ctemplate\u003e [output]\n```\n\n#### options\n\n\u003cdl\u003e\n\u003cdt\u003e-p, --prams \u0026lt;file\u0026gt;\u003c/dt\u003e\n\u003cdd\u003eA json or yaml file includes template variables.\u003c/dd\u003e\n\u003c/dl\u003e\n\n#### args\n\n\u003cdl\u003e\n\u003cdt\u003etemplate\u003c/dt\u003e\n\u003cdd\u003ePath to template file.\u003c/dd\u003e\n\u003cdt\u003eoutput\u003c/dt\u003e\n\u003cdd\u003ePath to output file. STDOUT will be used when \"-\" is supplied or ommitted.\n\u003c/dl\u003e\n\n#### Example\n\n```bash\nyipt -p params.yml my-template.yml out.pdf\n```\n\n### in JavaScript or TypeScript\n\n```typescript\nimport yipt from \"yipt\";\nimport * as PDFKit from \"pdfkit\";\n\nconst doc = new PDFKit();\nconst templateVariables = { foo: \"template variables\" };\n\nyipt.render(doc, \"/path/to/template.yml\", templateVariables);\n// yipt.render returns Promise\u003cvoid\u003e\n```\n\nIt's also possible to create new Yipt instance.\n\n```typescript\nimport { Yipt } from \"yipt\";\n\nconst yipt = new Yipt();\n```\n### Variable evaluation\nYipt supports template variables.\nMany of parameters in template are evaluated with template variables using [JSONata](http://jsonata.org/).\n\nValues in template other than text value such as content property of TextElement, are evaluated as a JSONata expression.\nOf course, you can also specify raw values instead of JSONata expressions for properties.\nTypes of properties documented in this doc, are types of evaluated value.\n\nOn the other hand, in text, JSONata expression is wrapped with `\"{\"` and `\"}\"`.\nFor escape `\"\\\"` is available.\n\n#### Example\n\ntemplate:\n```yaml\nyipt:\n  version: \"1.0\"\n  content:\n    - type: text\n      top: myVariableForTop\n      left: myObject.left\n      content: This text placed on (myObject.left, myVariableForTop).\n```\nvariables:\n```yaml\n{\n  myVariableForTop: 10,\n  myObject: { left: 20 },\n}   \n```\nThen, `\"This text placed on (myObject.left, myVariableForTop).\"` is rendered at (20, 10).\n\ntemplate:\n```yaml\nyipt:\n  version: \"1.0\"\n  content:\n    - |\n    Hello {foo.bar}! You can also use JSONata expression a + 1 = {a + 1}.\n    \\{but this never evaluted} because \\{ is escaped.\n    Then \"\\\\\\{\" and \"\\\\\\\\\" is rendered as \"\\{\" and \"\\\\\".\n```\nvariables:\n```yaml\n{\n  foo: { bar: \"world\" },\n  a: 2\n}\n```\n\noutput:\n```\n    Hello world! You can also use JSONata expression a + 1 = 3.\n    {but this never evaluted} because { is escaped.\n    Then \"\\{\" and \"\\\\\" is rendered as \"{\" and \"\\\".\n```\n\n## Template\n\n### Absatract\nYipt template is a YAML file whose root object has `yipt` property, which is a Yipt object.\nAnd Yipt object has `content` property, which is an array of Element object or string.\nIf element of `content` is a string, it is treated as TextElement.\n\nYipt renders Elements in order of array.\n\nElement object is one of:\n\nElement name|Description\n---|---\nTextElement| Renders text.\nImageElement| Renders JPEG/PNG image.\nVectorElement| Renders vector graphics.\nFontElement| Setup font for text.\nPageBreakElement|Insert page break.\nBlockElement|Groups elements and control offset.\nCaseElement|Logical flow control in similar way to SQL's CASE syntax.\nForeachElement|Loop flow control.\n\n### Spec\n\n#### Yipt Object\n\nProperty| Type | Description\n---|:---:|---\nversion|string|fixed `\"1.0\"`. Version of template format.\ncontent|Content[]| List of content.\n\n##### Content\n`Content` is one of `Element` or `string`.\n\n#### TextElement\n\nProperty| Type | Description\n---|:---:|---\ncontent|string|The text to print with variable reference.\ntop|number|The position in y axis.\nleft|number|The position in x axis.\noptions|TextOptions|Options for text rendering.\n\n##### TextOptions\n\nSee [Text in PDFKit](http://pdfkit.org/docs/text.html) for more detail.\n\n#### ImageElement\n\nProperty| Type | Description\n---|:---:|---\nsrc|string|Path to image(JPEG/PNG) file.\ntop|number|The position in y axis.\nleft|number|The position in x axis.\noptions|ImageOptions|Options for text rendering.\n\n##### ImageOptions\n\nSee [Images in PDFKit](http://pdfkit.org/docs/images.html) for more detail.\n\n#### VectorElement\n\nProperty| Type | Description\n---|:---:|---\npaths|VectorPath[]|Ordered array of vector paths.\ntop|number|The position in y axis.\nleft|number|The position in x axis.\nrender|\"stroke\" \u0026VerticalLine; \"fill\" \u0026VerticalLine; \"fillAndStroke\"| How render the path.\nlineWidth|number|Line width. lineWidth 0 means hair line.\ncap|\"butt\" \u0026VerticalLine; \"round\" \u0026VerticalLine; \"square\"|Line cap.\njoin|\"miter\" \u0026VerticalLine; \"round\" \u0026VerticalLine; \"bevel\"|Line join.\ndash|DashParameter|Line dash style.\ncolor|string|Line color. It allows a hex color string, or use any of the named CSS colors.\nfillColor|string|Fill color. It allows a hex color string, or use any of the named CSS colors.\nwindingRule|\"even-odd\" \u0026VerticalLine; \"non-zero\"|Winding rules define how a path is filled.\nopacity|number|Opacity of vector graphic. It value could be 0 to 1.\n\n##### VectorPath\n\nType property of VectorPath could be one of:\n- line\n- verticalLine\n- horizontalLine\n- quadraticCurve\n- bezierCurve\n- move\n- rect\n- roundedRect\n- ellipse\n- circle\n- polygon\n\nThe first 5 types(lines and curves) use end point of previous path as start point.(this means they connect previous path).\nUse `move` for change start point of them if you want.\n(0, 0) is used as start position if one of them placed in the first of paths array.\nPlease note that end points of the last 5 types(shapes) is undefined.\n\nVectorPath object has additional properties for each types.\n\n`doc.y` is set to maximum y of graphics after rendering vector. \n\n###### line\n\nProperty|Type|Description\n---|:---:|---\nto|[number, number]|Line end point in [x, y].\n\n###### verticalLine \u0026 horizontalLine\n\nProperty|Type|Description\n---|:---:|---\nlength|number|Line length.\n\n###### quadraticCurve\n\nProperty|Type|Description\n---|:---:|---\nto|[number, number]|Curve end point in [x, y].\nanchor|[number, number]|Anchor point in [x, y].\n\n###### bezierCurve\n\nProperty|Type|Description\n---|:---:|---\nto|[number, number]|Curve end point in [x, y].\nanchors|[number, number, number, number]|Anchor points in [x1, y1, x2, y2].\n\n###### move\nProperty|Type|Description\n---|:---:|---\nto|[number, number]|Move to [x, y].\n\n###### rect\nProperty|Type|Description\n---|:---:|---\npos|[number, number]|Position of rectangle in [left, top].\n\n\n###### roundedRect\n\nProperty|Type|Description\n---|:---:|---\npos|[number, number]|Position of rectangle in [left, top].\ncornerRadius|number|Radius of rounded corner.\n\n###### ellipse\nProperty|Type|Description\n---|:---:|---\ncenter|[number, number]|Center coordinate in [x, y].\nradiusX|number|Radius of x axis.\nradiusY|number|Radius of y axis.\n\n###### circle\nProperty|Type|Description\n---|:---:|---\ncenter|[number, number]|Center coordinate in [x, y].\n\n###### polygon\nProperty|Type|Description\n---|:---:|---\nvertices|number[]|Coordinates of vertices in [x1, y1, x2, y2, ...]\n\n#### FontElement\nYou can set or register founts using FontElement.\nOnce fount is configured, it affects all text rendering (even where out of BlockElement) until another FontElement configures font.\n\nProperty| Type | Description\n---|:---:|---\nsize|number|Set font size.\nname|string|Font name to be used. Standard font name or registered font name.\nsrc|string|Path to font file for register or temporally use.\nfamily|string|Font family for TrueType Collection or Datafork TrueType font file. This property is only used with `src` property.\nregisterAs|string|Register font as this value name. This property requires `src` property.\nsetOnRegister|boolean|Whether setting font on register or not. This property is only used with `registerAs`.\n Default is `false` unless `size` property is set together.\n\n#### PageBreakElement\nProperty| Type | Description\n---|:---:|---\noptions|PageOptions|Options for new page after page break.\n\nNOTE: PageOptions is never evaluated with variables.\n\n##### PageOptions\nProperty| Type | Description\n---|:---:|---\nsize|[number, number] \u0026VerticalLine; string|Page size in [width, height] or string such as \"A4\".\nlayout|\"portrait\" \u0026VerticalLine; \"landscape\"|Page layout. Default is \"portrait\".\nmargins|Margins|Margins of the new page.\nmargin|number|Syntax sugar for margins if all margins is the same.\n\n###### Margins\n\nProperty| Type | Description\n---|:---:|---\ntop|number|The top margin.\nleft|number|The left margin.\nbottom|number|The bottom margin.\nright|number|The right margin.\n\n\n#### BlockElement\n\nProperty| Type | Description\n---|:---:|---\ntop|number|Top position of the block.\nleft|number|Left position of the block.\ncontent|Content[]| List of content.\n\n#### CaseElement\nProperty| Type | Description\n---|:---:|---\nconditions|CaseCondition[]|Ordered list of conditions.\nelse|Content|This content will be rendered when any conditions isn't satisfied.\n\n##### CaseCondition\nProperty| Type | Description\n---|:---:|---\nwhen|boolean|The condition to be satisfied. Usually this is JSONata condition expression.\ncontent|Content|This content will be rendered if condition is satisfied.\n\n#### ForeachElement\nProperty| Type | Description\n---|:---:|---\nitems|any[]|Items to be iterate.\ncontent|Content|This will be rendered foreach loop.\n\nIn the loop, special variables are available.\n\n##### Loop variables\nAccessor|Type|Description\n---|:---:|---\n$foreach|Foreach|Current loop.\n$foreach.total|number|Total number of loop items.\n$foreach.index|number|Current item index.\n$foreach.count|number|The loop count.\n$foreach.item|any|Current item.\n$loops|Foreach[]|`$loops[0]` is the same as `$foreach`. `$loops[1]` is one outer loop.\n\n## Example\n\nYou can see example in [tests directory](tests/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebnium%2Fyipt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebnium%2Fyipt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebnium%2Fyipt/lists"}