You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The {% codeblock %} extension for Twig is a port of the [Octopress codeblock liquid tag](https://github.com/octopress/codeblock) for use with the [Twig template engine for PHP](http://twig.sensiolabs.org/).
7
7
8
-
### Using the codeblock tag
8
+
By default, Codeblock uses the [Pygments Python syntax highlighter](http://pygments.org/) for generating HTML mark-up suitable for highlighting blocks of code. However, it is flexible enough to use any syntax highlighter of your choice; simply implement the `HighlighterInterface` and provide some additional configuration (see below for an example).
9
9
10
-
Highlight your source code...
10
+
## Using the Codeblock tag
11
+
12
+
To highlight blocks of code, start the code block with the `{% codeblock %}` tag and end it with the `{% endcodeblock %}` tag. For example:
11
13
12
14
{% codeblock lang:php %}
15
+
<?php
13
16
namespace Foo;
14
17
15
18
/**
@@ -31,10 +34,88 @@ Highlight your source code...
31
34
}
32
35
{% endcodeblock %}
33
36
37
+
A number of options are available to Codeblock:
38
+
39
+
Option | Description
40
+
----------- | ------------
41
+
lang | the programming language used in the code block
42
+
format | the output format (defaults to "html")
43
+
linenos | "true" to turn on line numbers (defaults to "false")
44
+
start | starting line number, if linenos is "true"
45
+
end | ending line number, if linenos is "true"
46
+
range | starting and ending line numbers, overrides start and end (e.g. "101-118")
47
+
mark | marks one or more lines of code to be highlighted in the output (e.g. "102,111-113,117")
48
+
phpopentag | "false" to highlight PHP code without needing the PHP open tag (defaults to "true")
49
+
50
+
In addition to the options, you may also pass three text attributes. These are not named and must be wrapped in quotation marks (see example).
51
+
52
+
Attribute | Description
53
+
----------- | ------------
54
+
title | Provides a `<figcaption>` title for the code block
55
+
link | Provides a link to the external source of the code, if desired
56
+
link text | Provides the text to use for the link, otherwise "link" is used
57
+
58
+
A more complex example:
59
+
60
+
{% codeblock lang:php phpopentag:false start:11 mark:3,8 "Methods on a Class" "http://example.com/full-listing" %}
61
+
public function __construct(BazInterface $baz)
62
+
{
63
+
$this->baz = $baz;
64
+
}
65
+
66
+
public function doIt()
67
+
{
68
+
return $this->baz->do('it');
69
+
}
70
+
{% endcodeblock %}
71
+
72
+
## Output
73
+
74
+
If using "html" as the format output (which is the default), the resulting HTML output will wrap the highlighted code in a `<figure>` element. If you have provided a title and link, a `<figcaption>` will also be present.
75
+
76
+
Here's an example of HTML output that Pygments might generate, including the figure and figcaption elements provided by Codeblock (cleaned up for readability):
34
77
35
-
#### Pygments lexers
78
+
```html
79
+
<figureclass="code-highlight-figure">
80
+
<figcaptionclass="code-highlight-caption">
81
+
<spanclass="code-highlight-caption-title">Methods on a Class</span>
By default, Pygments is used for highlighting code. You will need to [install Pygments](http://pygments.org/) 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`.
103
+
104
+
### Styles
105
+
106
+
A syntax highlighter, such as Pygments, requires a stylesheet for the markup it generates. Pygments provides some styles for you, which you may list from the command line:
107
+
108
+
pygmentize -L styles
109
+
110
+
To output and save one of these styles for use in your application, use:
111
+
112
+
pygmentize -S default -f html > default.css
113
+
114
+
Additionally, there are many custom Pygments styles found on the web, and you may create your own.
115
+
116
+
### Languages
117
+
118
+
If you're using Pygments, here are a few of the languages (lexers) it supports:
38
119
39
120
* bash, sh, ksh, shell
40
121
* console
@@ -62,20 +143,17 @@ To see more, type the following from the command line:
62
143
63
144
pygmentize -L lexers
64
145
146
+
## Configuration
65
147
66
-
### Using the built-in Pygments helper
67
-
68
-
By default, the extension uses Pygments and, if `pygmentize` is in your `PATH`,
69
-
then you do not need to pass any arguments.
148
+
By default, the extension uses Pygments and, if `pygmentize` is in your `PATH`, then you do not need to pass any arguments.
70
149
71
150
services:
72
151
ramsey.twig.codeblock_extension:
73
152
class: Ramsey\Twig\CodeBlock\CodeBlockExtension
74
153
tags:
75
154
- { name: twig.extension }
76
155
77
-
However, if `pygmentize` is not in the `PATH`, then you may specify it's
78
-
location, like this:
156
+
However, if `pygmentize` is not in the `PATH`, then you may specify its location, like this:
79
157
80
158
services:
81
159
ramsey.twig.codeblock_extension:
@@ -87,14 +165,9 @@ location, like this:
87
165
- [/usr/local/bin/pygmentize]
88
166
89
167
90
-
###Using your own highlighter
168
+
## Using your own highlighter
91
169
92
-
If you have your own highlighter class that implements
93
-
`Ramsey\Twig\CodeBlock\Highlighter\HighlighterInterface`, then you may specify
94
-
the fully-qualified classname as the first argument to the extension. The second
95
-
argument is an array of 0-indexed values that will be passed as arguments to
96
-
your class constructor. Make sure that you specify them in the correct order as
97
-
your constructor requires.
170
+
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.
0 commit comments