{"id":15059300,"url":"https://github.com/factorial-io/eleventy-plugin-twig","last_synced_at":"2025-04-10T05:23:22.547Z","repository":{"id":41163155,"uuid":"491871966","full_name":"factorial-io/eleventy-plugin-twig","owner":"factorial-io","description":"Twig.js for Eleventy","archived":false,"fork":false,"pushed_at":"2025-01-13T19:32:04.000Z","size":87,"stargazers_count":14,"open_issues_count":5,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-03T01:33:46.586Z","etag":null,"topics":["11ty","11ty-plugin","eleventy","eleventy-plugin","twig","twigjs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/factorial-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2022-05-13T11:31:58.000Z","updated_at":"2025-03-20T15:22:02.000Z","dependencies_parsed_at":"2025-02-16T16:34:18.690Z","dependency_job_id":"a2728195-1539-4170-b75e-bd7fabb5dfc1","html_url":"https://github.com/factorial-io/eleventy-plugin-twig","commit_stats":{"total_commits":6,"total_committers":5,"mean_commits":1.2,"dds":0.6666666666666667,"last_synced_commit":"d1add3b8688c0436be8cbcdbedbaf0dd76583bf9"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factorial-io%2Feleventy-plugin-twig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factorial-io%2Feleventy-plugin-twig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factorial-io%2Feleventy-plugin-twig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/factorial-io%2Feleventy-plugin-twig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/factorial-io","download_url":"https://codeload.github.com/factorial-io/eleventy-plugin-twig/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248161730,"owners_count":21057643,"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":["11ty","11ty-plugin","eleventy","eleventy-plugin","twig","twigjs"],"created_at":"2024-09-24T22:40:56.977Z","updated_at":"2025-04-10T05:23:22.526Z","avatar_url":"https://github.com/factorial-io.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [Eleventy](https://www.11ty.dev) + [Twig.js](https://github.com/twigjs/twig.js/)\n\n\u003cp style=\"font-size: 2rem\"\u003e\n\u003cimg\n  style=\"margin:2rem; width:8rem; height:8rem;\"\n  align=\"center\"\n  width=\"128\"\n  height=\"128\"\n  alt=\"Eleventy Logo\"\n  src=\"https://camo.githubusercontent.com/124e337fb005b0e70eb3758b431b051eaf5419b3a709062fbcce6d661a6ea116/68747470733a2f2f7777772e313174792e6465762f696d672f6c6f676f2d6769746875622e737667\"\u003e+\n\u003cimg\n  style=\"margin:2rem; width:8rem; height:8rem;\"\n  align=\"center\"\n  width=\"128\"\n  height=\"128\"\n  alt=\"Twig.js Logo\"\n  src=\"https://user-images.githubusercontent.com/3282350/29336704-ab1be05c-81dc-11e7-92e5-cf11cca7b344.png\"\u003e\n\u003c/p\u003e\n\nThis package adds a `.twig` template engine to Eleventy that lets you use the pure JavaScript implementation of the [Twig PHP templating language ](http://twig.sensiolabs.org/) called [Twig.js](https://github.com/twigjs/twig.js/).\n\n## Features\n\n- **Built-in Shortcodes**: Uses [`twig.extendFunction()`](https://twig.symfony.com/doc/2.x/advanced.html) to extend Twig\n- **Twig Namespaces**: Uses `Twig` built-in loaders to provide [namespaces](https://twig.symfony.com/doc/3.x/api.html#built-in-loaders)\n- **Responsive Images**: Uses [`@11ty/eleventy-img`](https://github.com/11ty/eleventy-img) plugin to autogenerate responsive images\n- **Hashed Assets**: If you have generated a manifest (e.g. with [`@factorial/eleventy-plugin-fstack`](https://github.com/factorial-io/eleventy-plugin-fstack)) you could let Eleventy replace unhashed assets like `css/js` automatically with their hashed versions\n\n## Getting Started\n\nInstall the latest `@factorial/eleventy-plugin-twig` release as well as `twig` and optionally `@11ty/eleventy-img` as node modules with `yarn`:\n\n```sh\nyarn add --dev @factorial/eleventy-plugin-twig @11ty/eleventy-img twig\n```\n\nor `npm`:\n\n```sh\nnpm install --save-dev @factorial/eleventy-plugin-twig @11ty/eleventy-img twig\n```\n\n## Usage\n\nFor Eleventy to recognize this you have to **register this as a plugin**. To do so modify the `.eleventy.js` config file:\n\n```js\nconst eleventyPluginTwig = require(\"@factorial/eleventy-plugin-twig\");\n\nmodule.exports = function(eleventyConfig) {\n  ...\n  eleventyConfig.addPlugin(eleventyPluginTwig, USER_OPTIONS);\n  ...\n}\n```\n\nAs mentioned in the `eleventyConfig.addPlugin(eleventy-plugin-twig, USER_OPTIONS)` some options can be defined **optionally**. Currently `@factorial/eleventy-plugin-twig` provides the following configuration object:\n\n```js\n/**\n * @typedef {object} ELEVENTY_DIRECTORIES\n * @property {string} input - Eleventy template path\n * @property {string} output - Eleventy build path\n * @property {string} [includes] - Eleventy includes path relativ to input\n * @property {string} [layouts] - Eleventy separate layouts path relative to input\n * @property {string} [watch] - add more watchTargets to Eleventy\n */\n\n/**\n * @typedef {object} ASSETS\n * @property {string} root - path to the root folder from projects root (e.g. src)\n * @property {string} base - base path for assets relative to the root folder (e.g. assets)\n * @property {string} css - path to the css folder relative to the base (e.g. css)\n * @property {string} js - path to the js folder relative to the base (e.g. js)\n * @property {string} images - path to the image folder relative to the base (e.g. images)\n */\n\n/**\n * @typedef {object} IMAGES\n * @property {Array\u003cnumber\u003e} widths - those image sizes will be autogenereated / aspect-ratio will be respected\n * @property {Array\u003cimport(\"@11ty/eleventy-img\").ImageFormatWithAliases\u003e} formats - jpeg/avif/webp/png/gif\n * @property {string} additionalAttributes - those attributes will be added to the image element\n */\n\n/**\n * @typedef {object} SHORTCODE\n * @property {string} symbol - method name for twig to register\n * @property {function(import(\"@11ty/eleventy\").UserConfig, USER_OPTIONS, ...* ):any} callback - callback which is called by twig\n */\n\n/**\n * @typedef {object} TWIG_OPTIONS\n * @property {SHORTCODE[]} [shortcodes] - array of shortcodes\n * @property {boolean} [cache] - you could enable the twig cache for whatever reasons here\n * @property {Object\u003cstring, string\u003e} [namespaces] - define namespaces to include/extend templates more easily by \"@name\"\n */\n\n/**\n * @typedef {object} USER_OPTIONS\n * @property {string} [mixManifest] - path to the mixManifest file relative to the build folder\n * @property {ASSETS} [assets] - where to find all the assets relative to the build folder\n * @property {IMAGES} [images] - options for Eleventys image processing\n * @property {ELEVENTY_DIRECTORIES} dir - Eleventy folder decisions\n * @property {TWIG_OPTIONS} [twig] - twig options\n */\n```\n\nYou could use this as a starting point and customize to your individual needs:\n\n```js\n/**\n * @type {USER_OPTIONS} USER_OPTIONS\n */\nconst USER_OPTIONS = {\n  twig: {\n    namespaces: {\n      elements: \"src/include/elements\",\n      patterns: \"src/include/patterns\",\n      \"template-components\": \"src/include/template-components\",\n      templates: \"src/include/templates\",\n    },\n  },\n  mixManifest: \"mix-manifest.json\",\n  assets: {\n    root: \"src\",\n    base: \"assets\",\n    css: \"css\",\n    js: \"js\",\n    images: \"images\",\n  },\n  images: {\n    widths: [300, 600, 900],\n    formats: [\"webp\", \"avif\", \"jpeg\"],\n    additionalAttributes: \"\",\n  },\n  dir: {\n    output: \"build\",\n    src: \"src\",\n    input: \"src/include/templates\",\n    layouts: \"src/layouts\",\n    watch: \"src/**/*.{css,js,twig}\",\n  },\n};\n```\n\n## Shortcodes\n\n### `mix`\n\nIf you've generated a mixManifest and add the path to it to the `USER_OPTIONS` then it's possible to add the non hashed files to a template e.g.:\n\n```twig\n{{ mix(\"/path/to/unhashed/asset.css\") }} --\u003e will result in /path/to/hashed/asset.hash-1234.css\n```\n\nPlease provide a path relative so that `userOptions.assets.root + userOptions.base + providedPath` reaches the asset from your projects root.\n\n### `asset_path`\n\nThis is a simple helper shortcode to make your defined asset path `userOptions.assets.base` available in a template:\n\n```twig\n{{ asset_path() }} --\u003e will result in /userOptions.assets.base like \"/assets\"\n```\n\n### `image`\n\nThis uses `@11ty/eleventy-img` to generate responsive images in defined formats (`userOptions.images.formats`) and sizes (`userOptions.images.widths`). You could also provide certain additionalAttributes via config for lazyloading etc.\n\n```twig\n{{ image(\"src\", \"alt\", \"classes\") }} --\u003e will result in a proper \u003cpicture\u003e element with different \u003csource\u003e elements for each format and defined widths\n```\n\n- `src`: this has to be relative to the `userOptions.assets.images` folder\n- `alt`: mandatory! (`\"\"` is possible)\n- optional `classes`: `Array\u003cstring\u003e`\n\n## To be done\n\n- Proper caching\n- Make features optional\n- ...\n\n## Acknowledgements\n\nThis **Eleventy + Twig.js** plugin uses open source software and would not have been possible without the excellent work of the [Eslint](https://babeljs.io/team), [Eleventy](https://www.11ty.dev/docs/credits/), [Prettier](https://unifiedjs.com/community/member/), [debug](https://github.com/debug-js/debug) and [Twig.js](https://github.com/twigjs/twig.js/) teams! Thanks a lot!\n\n## Sponsored by\n\n\u003ca href=\"https://factorial.io\"\u003e\u003cimg src=\"https://logo.factorial.io/color.png\" width=\"40\" height=\"56\" alt=\"Factorial\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffactorial-io%2Feleventy-plugin-twig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffactorial-io%2Feleventy-plugin-twig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffactorial-io%2Feleventy-plugin-twig/lists"}