A Twig extension for defining blocks of code for syntax highlighting (with Pygments) and more.

2.0.0 2017-04-18 07:37 UTC

This package is auto-updated.

Last update: 2024-01-29 02:32:24 UTC


Add code snippets with syntax highlighting and more to any Twig template.

Source Code Latest Version Software License Build Status Coverage Status Total Downloads

The Codeblock extension for Twig is a port of the {% codeblock %} liquid tag for Octopress/Jekyll.

By default, Codeblock uses Pygments, the Python syntax highlighter, to generate HTML markup suitable for highlighting blocks of code, but it may use any syntax highlighter. To use another syntax highlighter, simply implement HighlighterInterface (see below for an example).

This project adheres to a Contributor Code of Conduct. By participating in this project and its community, you are expected to uphold this code.


The preferred method of installation is via Packagist and Composer. Run the following command to install the package and add it as a requirement to your project's composer.json:

composer require ramsey/twig-codeblock


{% codeblock [options] %}
[lines of code]
{% endcodeblock %}


A number of options are available to Codeblock. Note that order does not matter.

Option Example Description
lang lang:"php" Tells the syntax highlighter the programming language being highlighted. Pass "plain" to disable highlighting.
title title:"Figure 2." Add a title to your code block.
link link:"https://example.com" Add a link to your code block title.
link_text link_text:"Download Code" Text to use for the link. Defaults to "link".
linenos linenos:false Use false to disable line numbering. Defaults to true.
start start:42 Start the line numbering in your code block at this value.
mark mark:4-6,12 Mark specific lines of code. This example marks lines 4, 5, 6, and 12.
class class:"myclass foo" Add CSS class names to the code <figure> element.
format format:"html" The output format for the syntax highlighter. Defaults to "html."


{% codeblock lang:"php" %}
class Bar implements BarInterface
    private $baz;

    public function __construct(BazInterface $baz)
        $this->baz = $baz;

    public function doIt()
        return $this->baz->do('it');
{% endcodeblock %}


By default, Codeblock uses Pygments and, if pygmentize is in your PATH, then you do not need to pass any arguments.

use Ramsey\Twig\CodeBlock\CodeBlockExtension;

$env = new \Twig_Environment(new \Twig_Loader_Filesystem('/path/to/templates'));
$env->addExtension(new CodeBlockExtension());

If pygmentize is not in the PATH, you may specify its location:

use Ramsey\Twig\CodeBlock\CodeBlockExtension;

$env = new \Twig_Environment(new \Twig_Loader_Filesystem('/path/to/templates'));
    new CodeBlockExtension('pygments', ['/usr/local/bin/pygmentize'])


By default, Pygments is used for highlighting code. You will need to install Pygments and ensure that the pygmentize CLI tool is available on your system. See the Configuration section for help configuring Codeblock if pygmentize is not in your PATH.

pip install Pygments


A syntax highlighter, such as Pygments, requires a stylesheet for the markup it generates. Pygments provides some stylesheets for you, which you may list from the command line:

pygmentize -L styles

To output and save one of these styles for use in your application, use:

pygmentize -S solarizedlight -f html > solarizedlight.css

Additionally, there are many custom Pygments styles found on the web, and you may create your own.


If using Pygments, here are just a few of the languages (lexers) it supports:

  • css
  • diff
  • html
  • html+php
  • javascript
  • json
  • php
  • sass
  • shell
  • sql
  • twig
  • yaml

To see more, type the following from the command line:

pygmentize -L lexers

Using your own highlighter

If you have your own highlighter class that implements Ramsey\Twig\CodeBlock\Highlighter\HighlighterInterface, then you may specify the fully-qualified classname as the first argument to the extension. The second argument is an array of 0-indexed values that will be passed as arguments to your class constructor. Make sure that you specify them in the correct order as your constructor requires.

use Ramsey\Twig\CodeBlock\CodeBlockExtension;
use Your\Own\Highlighter as MyHighlighter;

$env = new \Twig_Environment(new \Twig_Loader_Filesystem('/path/to/templates'));
    new CodeBlockExtension(MyHighlighter::class, ['arg1', 'arg2', 'arg3'])


Contributions are welcome! Please read CONTRIBUTING for details.

Copyright and license

The ramsey/twig-codeblock library is copyright © Ben Ramsey and licensed for use under the MIT License (MIT). Please see LICENSE for more information.