{"id":15380766,"url":"https://github.com/bitstarr/grav-plugin-svg-extension","last_synced_at":"2025-04-15T18:40:53.612Z","repository":{"id":56008808,"uuid":"247045967","full_name":"bitstarr/grav-plugin-svg-extension","owner":"bitstarr","description":"Inline SVG in Twig Templates","archived":false,"fork":false,"pushed_at":"2023-08-01T21:42:25.000Z","size":28,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-28T23:43:50.204Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","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/bitstarr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2020-03-13T10:31:56.000Z","updated_at":"2024-03-28T21:30:41.000Z","dependencies_parsed_at":"2024-10-17T21:14:18.172Z","dependency_job_id":"7244cf84-67c7-403c-ae0d-4ae95f10166e","html_url":"https://github.com/bitstarr/grav-plugin-svg-extension","commit_stats":{"total_commits":9,"total_committers":3,"mean_commits":3.0,"dds":0.4444444444444444,"last_synced_commit":"f4b8d13e10f6ae3f8336367b73b473a2454e955d"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitstarr%2Fgrav-plugin-svg-extension","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitstarr%2Fgrav-plugin-svg-extension/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitstarr%2Fgrav-plugin-svg-extension/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitstarr%2Fgrav-plugin-svg-extension/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitstarr","download_url":"https://codeload.github.com/bitstarr/grav-plugin-svg-extension/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249130699,"owners_count":21217596,"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":[],"created_at":"2024-10-01T14:24:33.161Z","updated_at":"2025-04-15T18:40:53.589Z","avatar_url":"https://github.com/bitstarr.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SVG Extension Plugin\n\nThe **SVG Extension** Plugin is an extension for [Grav CMS](http://github.com/getgrav/grav). It provides a way to inline SVG files in your Twig templates so you can style them with CSS. In 1.1.0 a way to create [sprites](#sprites) was added.\n\n\u003e Remember Minifying: To keep the amount of markup low, consider an automated workflow (involving gulp/grunt and svgo for example) to minimize the filesize of the SVG files by optimizing them. Here we are assume that you have an ``assets/svg`` folder with the source files and ``dist/svg`` with the optimized copies. Only the latter will be transfered to the production enviroment in this scenario.\n\n## Usage\n\nYou can access your SVG files in two ways.\n\n### Access by filename\nFirst you can set a base path in the plugin config and access them by filename:\n\n````twig\n{{ svg( 'search' )|raw }}\n````\n\nThis will lookup ``search.svg`` in the icons folder. The default icon folder is ``theme://dist/icons/`` and can be set in the [configuration](#configuration).\n\n### Access with absolute path\nThe second way is to use a somehow absolute path:\n\n````twig\n{{ svg('theme://optimized/icons/search.svg', 'icon')|raw }}\n````\n\n### Parameters\n\nFirst parameter is the path or filname (as mentioned above). The second is the place for CSS classes. The third is an object/associative array. This array accepts up to three items at the moment:\n* An ``id`` as the id attribute for the svg element embedded in the markup.\n* A ``title`` for better accessability\n* ``preserveAspectRatio`` for orientation, defaults to ``xMinYMin``\n\n````twig\n{{ svg('logo', 'icon logo__img', { 'id': 'logo-icon', 'title': 'Brand name' })|raw }}\n````\n\n\u003e About Accessibility: Without a title, the SVG will be placed as pesentational image. Take a look in the expamples tfor more details.\n\nThere is a [configuration](#configuration) option to set the default CSS classes, so you can use a very short call for simple, presentational icons:\n\n````twig\n{{ svg('info')|raw }}\n````\n\n### Example\n\n````css\n.icon {\n    fill: currentColor;\n    height: 1em;\n    width: 1em;\n    overflow: hidden;\n    vertical-align: -.125em;\n}\n.meta__item .icon {\n    color: rebeccapurple;\n}\n````\n\n````twig\n\u003cul class=\"meta\"\u003e\n    \u003cli class=\"meta__item\"\u003e\n        {{ svg('thumbtack')|raw }}\n    \u003c/li\u003e\n    \u003cli class=\"meta__item\"\u003e\n        {{ svg('clock', 'icon icon--mod', { 'title': 'Cooking Time' })|raw }}\n        10 Minutes\n    \u003c/li\u003e\n    …\n\u003c/ul\u003e\n````\n\nWill render to this:\n````html\n\u003cul class=\"meta\"\u003e\n    \u003cli class=\"meta__item\"\u003e\n        \u003csvg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 384 512\" class=\"icon\" role=\"img\" aria-hidden=\"true\" preserveAspectRatio=\"xMinYMin\"\u003e\n            \u003cpath d=\"M306.5 186.6l-5.7-42.6H328c13.2 0 24-10.8 24-24V24c0-13.2-10.8-24-24-24H56C42.8 0 32 10.8 32 24v96c0 13.2 10.8 24 24 24h27.2l-5.7 42.6C29.6 219.4 0 270.7 0 328c0 13.2 10.8 24 24 24h144v104c0 .9.1 1.7.4 2.5l16 48c2.4 7.3 12.8 7.3 15.2 0l16-48c.3-.8.4-1.7.4-2.5V352h144c13.2 0 24-10.8 24-24 0-57.3-29.6-108.6-77.5-141.4zM50.5 304c8.3-38.5 35.6-70 71.5-87.8L138 96H80V48h224v48h-58l16 120.2c35.8 17.8 63.2 49.4 71.5 87.8z\"\u003e\u003c/path\u003e\n        \u003c/svg\u003e\n    \u003c/li\u003e\n    \u003cli class=\"meta__item\"\u003e\n        \u003csvg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" class=\"icon icon--mod\" role=\"img\" aria-labelledby=\"icon__title--5e6b577f45c8b\" preserveAspectRatio=\"xMinYMin\"\u003e\n            \u003cpath fill=\"currentColor\" d=\"M256 8C119 8 8 119 8 256s111 248 248 248 248-111 248-248S393 8 256 8zm0 448c-110.5 0-200-89.5-200-200S145.5 56 256 56s200 89.5 200 200-89.5 200-200 200zm61.8-104.4l-84.9-61.7c-3.1-2.3-4.9-5.9-4.9-9.7V116c0-6.6 5.4-12 12-12h32c6.6 0 12 5.4 12 12v141.7l66.8 48.6c5.4 3.9 6.5 11.4 2.6 16.8L334.6 349c-3.9 5.3-11.4 6.5-16.8 2.6z\"\u003e\u003c/path\u003e\n            \u003ctitle id=\"icon__title--5e6b577f45c8b\"\u003eCooking Time\u003c/title\u003e\n        \u003c/svg\u003e\n        10 Minutes\n    \u003c/li\u003e\n    …\n\u003c/ul\u003e\n````\n![Rendered Preview](example.png)\n\n\n## Sprites\n\nTo create a sprite you take a similiar approach as for inlining SVGs dirctly. The difference is, that you provide an array of icons needed and you will refer them  elsewhere.\n\n````twig\n{{ svgSprite( [ 'search', 'phone', 'mail' ] )|raw }}\n````\n\nThe example above will place something like the following in your markup;\n\n````html\n\u003csvg style=\"display:none\"\u003e\n    \u003csymbol xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" id=\"icon-search\" preserveAspectRatio=\"xMinYMin\"\u003e\u003cpath fill=\"currentColor\" d=\"…\"/\u003e\u003c/symbol\u003e\n    \u003csymbol xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" id=\"icon-phone\" preserveAspectRatio=\"xMinYMin\"\u003e\u003cpath fill=\"currentColor\" d=\"…\"/\u003e\u003c/symbol\u003e\n    \u003csymbol xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 512 512\" id=\"icon-mail\" preserveAspectRatio=\"xMinYMin\"\u003e\u003cpath fill=\"currentColor\" d=\"…\"/\u003e\u003c/symbol\u003e\n\u003c/svg\u003e\n````\nTo make use of this hidden bunch of icons use the following, where you like to have the icon.\n\n````twig\n{{ sprite('mail', 'icon')|raw }}\n````\n\nWhich will output:\n\n```html\n\u003csvg class=\"icon\" aria-hidden=\"true\"\u003e\n    \u003cuse xlink:href=\"#icon-mail\" href=\"#icon-mail\"\u003e\u003c/use\u003e\n\u003c/svg\u003e\n```\n\nIf you want your content to be more accessable, use this:\n\n```twig\n{{ sprite('mail', null, 'E-Mail')|raw }}\n```\n\n````html\n\u003csvg class=\"icon\" role=\"img\" aria-labelledby=\"icon-email-title\" \u003e\n    \u003cuse xlink:href=\"#icon-mail\" href=\"#icon-mail\"\u003e\u003c/use\u003e\n    \u003ctitle id=\"icon-email-title\"\u003eE-Mail\u003c/title\u003e\n\u003c/svg\u003e\n````\n\n### Parameters\n\n**svgSprite**\n* The first parameter is an array of IDs/names\n* The second is an object that can only hold ``preserveAspectRatio`` for orientation, defaults to ``xMinYMin``\n\n````twig\n{{ svgSprite( [ 'search', 'phone', 'mail' ], { preserveAspectRatio: 'xMinYMin' } )|raw }}\n````\n\n**sprite**\n* First parameter is the ID/Name\n* Second is the custom class names, default is `icon`\n* Third is the title for better accessability, default is no title\n\n````twig\n{{ sprite('mail', 'icon', 'E-Mail')|raw }}\n````\n\n\n## Installation\n\nInstalling the SVG Extension plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.\n\n### GPM Installation (Preferred)\n\nTo install the plugin via the [GPM](http://learn.getgrav.org/advanced/grav-gpm), through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:\n\n    bin/gpm install svg-extension\n\nThis will install the SVG Extension plugin into your `/user/plugins`-directory within Grav. Its files can be found under `/your/site/grav/user/plugins/svg-extension`.\n\n### Manual Installation\n\nTo install the plugin manually, download the zip-version of this repository and unzip it under `/your/site/grav/user/plugins`. Then rename the folder to `svg-extension`. You can find these files on [GitHub](https://github.com//grav-plugin-svg-extension) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).\n\nYou should now have all the plugin files under\n\n    /your/site/grav/user/plugins/svg-extension\n\n\n### Admin Plugin\n\nIf you use the Admin Plugin, you can install the plugin directly by browsing the `Plugins`-menu and clicking on the `Add` button.\n\n## Configuration\n\nBefore configuring this plugin, you should copy the `user/plugins/svg-extension/svg-extension.yaml` to `user/config/plugins/svg-extension.yaml` and only edit that copy.\n\nHere is the default configuration and an explanation of available options:\n\n```yaml\nenabled: true\npath: 'theme://dist/icons/'   # Where are your SVG files stored?\ndefaultClass: 'icon'          # What's the default CSS classes?\n```\n\nNote that if you use the Admin Plugin, a file with your configuration named svg-extension.yaml will be saved in the `user/config/plugins/`-folder once the configuration is saved in the Admin.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitstarr%2Fgrav-plugin-svg-extension","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitstarr%2Fgrav-plugin-svg-extension","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitstarr%2Fgrav-plugin-svg-extension/lists"}