Usage¶
HTML¶
Load the template tags.
{% load pygmentify_tags %}
Use the {% filter pygmentify %}
template tag to covert HTML into Pygments HTML.
{% filter pygmentify %}
<pre class="python"><code>
print('Hello, world!')
</code></pre>
{% endfilter %}
Result:
<div class="highlight"><pre class="python"><code><span></span><span class="k">print</span><span class="p">(</span><span class="s2">"Hello, world!"</span><span class="p">)</span>
</code></pre></div>
The {% filter pygmentify %}
template tag expects an opening <pre>
tag with a class
attribute of the programming language that you are using. For example, <pre class="python">
uses Python, and <pre class="html">
uses HTML.
If no CSS class is specified, the template tag makes a best guess using heuristics of the code inside of the <pre>
element. If multiple CSS classes are specified, the first one is selected. The template tag also strips a possible language-
prefix that could be prepended to the first class.
Pygments’s default behavior strips your customized <pre class="...">
tag and replaces it with a plain <pre>
tag. The template tag undoes this unacceptable behavior and preserves the customized <pre class="...">
tag. Additionally, the inner contents of the <pre class="...">
are wrapped in a semantic <code>
element if no code
tags are present.
Consult the Pygments documentation for all language short names. There’s even a Django template one.
CSS¶
Use the {% pygmentify_css %}
template tag to output the URL of the CSS file.
<link rel="stylesheet" href="{% pygmentify_css %}">
Result:
<link rel="stylesheet" href="/static/pygmentify/css/default.min.css">
The way that Pygments generates CSS is awkward. Rather than provide CSS files, Pygments abstracts a more generalized style language into Python classes to create styles that can be used with formatters other than HTML. Therefore, the template tag provides exports of the default styles using the pygmentize
command and clean-css
library.
pygmentize -S <style> -f html > <style>.css
cleancss <style>.css -o <style>-min.css
Please remember to put the <link>
tag in the <head>
of your document.
Examples¶
{% load pygmentify_tags %}
<link rel="stylesheet" href="{% pygmentify_css %}">
{% filter pygmentify %}
<pre class="python"><code>
print('Hello, world!')
</code></pre>
{% endfilter %}
Customize the behavior by passing the name of a style into the {% pygmentify_css %}
tag and into the {% filter pygmentify %}
filter.
{% load pygmentify_tags %}
<link rel="stylesheet" href="{% pygmentify_css 'monokai' %}">
{% filter pygmentify:'monokai' %}
<pre class="python"><code>
print('Hello, world!')
</code></pre>
{% endfilter %}
Additionally customize the CSS class of the <div>
that wraps the highlighted code by passing a second positional argument to {% filter pygmentify %}
.
{% filter pygmentify:'monokai,bettercssclass' %}
<pre class="python"><code>
print('Hello, world!')
</code></pre>
{% endfilter %}
If you customize the style, please ensure you pass the same argument, e.g. 'monokai'
, to both the {% pygmentify_css %}
and {% filter pygmentify %}
tags. You might see unexpected behavior otherwise because “not all lexers might support every style,” meaning styles are guaranteed to work fully only when the lexer assigns to tokens HTML classes that correspond to the class selectors in the CSS file. Therefore, you’re probably better off customizing the style by changing the Settings of the project. Template tag arguments take precedence over settings. Also see Settings for creating your own styles.
If you use the pipe syntax, e.g. {{ post.body|pygmentify }}
, ensure that the variable contains HTML either natively or by conversion (by, say Markdown) because the template tag will look for the HTML outlined earlier.