{"id":20004738,"url":"https://github.com/ramsey/twig-codeblock","last_synced_at":"2025-05-04T17:31:05.893Z","repository":{"id":26713349,"uuid":"30170656","full_name":"ramsey/twig-codeblock","owner":"ramsey","description":"🌿 Syntax highlighting for Twig with the {% codeblock %} tag.","archived":false,"fork":false,"pushed_at":"2025-03-08T23:40:49.000Z","size":109,"stargazers_count":21,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T08:22:27.198Z","etag":null,"topics":["php","pygmentize","pygments","syntax-highlighting","twig","twig-extension"],"latest_commit_sha":null,"homepage":"","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/ramsey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-02T04:12:34.000Z","updated_at":"2025-03-31T01:37:14.000Z","dependencies_parsed_at":"2022-06-29T00:04:19.234Z","dependency_job_id":null,"html_url":"https://github.com/ramsey/twig-codeblock","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Ftwig-codeblock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Ftwig-codeblock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Ftwig-codeblock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ramsey%2Ftwig-codeblock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ramsey","download_url":"https://codeload.github.com/ramsey/twig-codeblock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252371706,"owners_count":21737386,"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":["php","pygmentize","pygments","syntax-highlighting","twig","twig-extension"],"created_at":"2024-11-13T05:32:43.287Z","updated_at":"2025-05-04T17:31:05.845Z","avatar_url":"https://github.com/ramsey.png","language":"PHP","readme":"\u003ch1 align=\"center\"\u003eramsey/twig-codeblock\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cstrong\u003e🌿 Syntax highlighting for Twig with the \u003ccode\u003e{% codeblock %}\u003c/code\u003e tag.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/ramsey/twig-codeblock\"\u003e\u003cimg src=\"https://img.shields.io/badge/source-ramsey/twig--codeblock-blue.svg?style=flat-square\" alt=\"Source Code\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/ramsey/twig-codeblock\"\u003e\u003cimg src=\"https://img.shields.io/packagist/v/ramsey/twig-codeblock.svg?style=flat-square\u0026label=release\" alt=\"Download Package\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://php.net\"\u003e\u003cimg src=\"https://img.shields.io/packagist/php-v/ramsey/twig-codeblock.svg?style=flat-square\u0026colorB=%238892BF\" alt=\"PHP Programming Language\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ramsey/twig-codeblock/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/packagist/l/ramsey/twig-codeblock.svg?style=flat-square\u0026colorB=darkcyan\" alt=\"Read License\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/ramsey/twig-codeblock/actions/workflows/continuous-integration.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/ramsey/twig-codeblock/continuous-integration.yml?branch=main\u0026logo=github\u0026style=flat-square\" alt=\"Build Status\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/ramsey/twig-codeblock\"\u003e\u003cimg src=\"https://img.shields.io/codecov/c/gh/ramsey/twig-codeblock?label=codecov\u0026logo=codecov\u0026style=flat-square\" alt=\"Codecov Code Coverage\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## About\n\nAdd code snippets with syntax highlighting and more to any [Twig][] template\nwith ramsey/twig-codeblock, a port of the `{% codeblock %}`\n[Liquid tag for Octopress/Jekyll][octopress-codeblock].\n\nramsey/twig-codeblock includes an adapter for using [Pygments][], the Python\nsyntax highlighter, with [ramsey/pygments][], but it may use any syntax\nhighlighter. To use another syntax highlighter, implement `HighlighterInterface`\n(see below for an example).\n\nThis project adheres to a [code of conduct](CODE_OF_CONDUCT.md).\nBy participating in this project and its community, you are expected to\nuphold this code.\n\n## Installation\n\nInstall this package as a dependency using [Composer](https://getcomposer.org).\n\n```bash\ncomposer require ramsey/twig-codeblock\n```\n\n## Usage\n\n```\n{% codeblock [attributes] %}\n[lines of code]\n{% endcodeblock %}\n```\n\n### Attributes\n\nA number of attributes are available to `{% codeblock %}`:\n\n| Attribute   | Example                      | Description                                                                                                    |\n|-------------|------------------------------|----------------------------------------------------------------------------------------------------------------|\n| `lang`      | `lang:\"php\"`                 | Tells the syntax highlighter the programming language being highlighted. Pass \"plain\" to disable highlighting. |\n| `title`     | `title:\"Figure 2.\"`          | Add a title to your code block.                                                                                |\n| `link`      | `link:\"https://example.com\"` | Add a link to your code block title.                                                                           |\n| `link_text` | `link_text:\"Download Code\"`  | Text to use for the link. Defaults to `\"link\"`.                                                                |\n| `linenos`   | `linenos:false`              | Use `false` to disable line numbering. Defaults to `true`.                                                     |\n| `start`     | `start:42`                   | Start the line numbering in your code block at this value.                                                     |\n| `mark`      | `mark:4-6,12`                | Mark specific lines of code. This example marks lines 4, 5, 6, and 12.                                         |\n| `class`     | `class:\"myclass foo\"`        | Add CSS class names to the code `\u003cfigure\u003e` element.                                                            |\n| `format`    | `format:\"html\"`              | The output format for the syntax highlighter. Defaults to \"html.\"                                              |\n\n\u003e [!TIP]\n\u003e Order of attributes does not matter.\n\n\u003e [!WARNING]\n\u003e Not all highlighters will support all attributes. However, the Pygments\n\u003e highlighter does support each of these attributes.\n\n### Example\n\n``` twig\n{% codeblock lang:\"php\" %}\nclass Bar implements BarInterface\n{\n    private $baz;\n\n    public function __construct(BazInterface $baz)\n    {\n        $this-\u003ebaz = $baz;\n    }\n\n    public function doIt()\n    {\n        return $this-\u003ebaz-\u003edo('it');\n    }\n}\n{% endcodeblock %}\n```\n\n### Configuration\n\nTo use ramsey/twig-codeblock, create a `HighlighterReference` that defines the\nhighlighter you want to use. If using `PygmentsHighlighter`, by default, it will\nlook for `pygmentize` in your `PATH`.\n\n``` php\nuse Ramsey\\Twig\\CodeBlock\\CodeBlockExtension;\nuse Ramsey\\Twig\\CodeBlock\\Highlighter\\HighlighterReference;\nuse Ramsey\\Twig\\CodeBlock\\Highlighter\\PygmentsHighlighter;\nuse Twig\\Environment;\nuse Twig\\Loader\\FilesystemLoader;\n\n$reference = new HighlighterReference(PygmentsHighlighter::class);\n\n$env = new Environment(new FilesystemLoader('/path/to/templates'));\n$env-\u003eaddExtension(new CodeBlockExtension($reference));\n```\n\nIf `pygmentize` is not in the `PATH`, you may pass its location to the\nhighlighter reference:\n\n``` php\n$reference = new HighlighterReference(\n    PygmentsHighlighter::class,\n    ['/path/to/pygmentize'],\n);\n```\n\n\u003e [!NOTE]\n\u003e We use a `HighlighterReference` instead of an actual instance of\n\u003e `HighlighterInterface` because these values will be compiled into the Twig\n\u003e templates and cached for later execution.\n\n### Pygments\n\nThis library provides `PygmentsHighlighter`, which depends on [ramsey/pygments][],\nbut ramsey/pygments is not a dependency, since you may use other highlighters\nthat implement `Ramsey\\Twig\\CodeBlock\\Highlighter\\HighlighterInterface`.\n\nTo use this library with ramsey/pygments, you must also require ramsey/pygments\nas a dependency:\n\n``` bash\ncomposer require ramsey/pygments\n```\n\nAdditionally, you will need to install [Python][] and [Pygments][] and ensure the\n`pygmentize` CLI tool is available on your system. See the [Configuration](#configuration)\nsection for help configuring Codeblock if `pygmentize` is not in your `PATH`.\n\n``` bash\npip install Pygments\n```\n\n#### Styles\n\nA syntax highlighter, such as Pygments, requires a stylesheet for the markup it\ngenerates. Pygments provides some stylesheets for you, which you may list from\nthe command line:\n\n``` bash\npygmentize -L styles\n```\n\nTo output and save one of these styles for use in your application, use\nsomething like:\n\n``` bash\npygmentize -S rainbow_dash -f html \u003e rainbow_dash.css\n```\n\nAdditionally, there are many custom Pygments styles found on the web, or you may\ncreate your own.\n\n#### Languages\n\nIf using Pygments, here are just a few of the languages (i.e., lexers) it supports:\n\n* css\n* diff\n* html\n* html+php\n* javascript\n* json\n* php\n* sass\n* shell\n* sql\n* twig\n* yaml\n\nTo see more, type the following from the command line:\n\n``` bash\npygmentize -L lexers\n```\n\n### Using your own highlighter\n\nIf you have your own highlighter class that implements `Ramsey\\Twig\\CodeBlock\\Highlighter\\HighlighterInterface`,\nyou may create a `HighlighterReference` using it. The array of values passed\nas the second argument will be passed to your class's constructor upon instantiation.\n\nThe arguments must be scalar values or arrays of scalar values, or they may be\nexpressions that evaluate to scalar values or arrays of scalar values. Null\nvalues are also allowed. This restriction is because of the way these values are\ncompiled into the Twig templates.\n\n``` php\nuse Ramsey\\Twig\\CodeBlock\\CodeBlockExtension;\nuse Ramsey\\Twig\\CodeBlock\\Highlighter\\HighlighterReference;\nuse Ramsey\\Twig\\CodeBlock\\Highlighter\\PygmentsHighlighter;\nuse Twig\\Environment;\nuse Twig\\Loader\\FilesystemLoader;\nuse Your\\Own\\Highlighter as MyHighlighter;\n\n$reference = new HighlighterReference(MyHighlighter::class, [$arg1, $arg2, $arg3]);\n\n$env = new Environment(new FilesystemLoader('/path/to/templates'));\n$env-\u003eaddExtension(new CodeBlockExtension($reference));\n```\n\n## Contributing\n\nContributions are welcome! To contribute, please familiarize yourself with\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Coordinated Disclosure\n\nKeeping user information safe and secure is a top priority, and we welcome the\ncontribution of external security researchers. If you believe you've found a\nsecurity issue in software that is maintained in this repository, please read\n[SECURITY.md](SECURITY.md) for instructions on submitting a vulnerability report.\n\n## Copyright and License\n\nThe ramsey/twig-codeblock library is copyright © [Ben Ramsey](https://benramsey.com/)\nand licensed for use under the MIT License (MIT). Please see [LICENSE](LICENSE)\nfor more information.\n\n[octopress-codeblock]: https://github.com/octopress/codeblock\n[python]: https://www.python.org\n[pygments]: http://pygments.org/\n[twig]: https://twig.symfony.com\n[ramsey/pygments]: https://github.com/ramsey/pygments\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsey%2Ftwig-codeblock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framsey%2Ftwig-codeblock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framsey%2Ftwig-codeblock/lists"}