README

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

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.

Installation

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

Usage

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

Options

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."

Example

{% 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 %}

Configuration

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'));
$env->addExtension(
    new CodeBlockExtension('pygments', ['/usr/local/bin/pygmentize'])
);

Pygments

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

Styles

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.

Languages

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'));
$env->addExtension(
    new CodeBlockExtension(MyHighlighter::class, ['arg1', 'arg2', 'arg3'])
);

Contributing

Contributions are welcome! Please read CONTRIBUTING for details.

ramsey / twig-codeblock

Maintainers

Details