Pygments Examples

The pygments filter applies syntax highlighting to source code.

Here is some raw source code:

print "Hello!"

And here is how we specify in dexy.yaml that the pyg filter should be applied to this file:

- hello.py|pyg

The default format is HTML, so the code will come out looking like this, with HTML markup applied:

<div class="highlight"><pre><span></span><a name="hello.py-pyg.html-1"></a><span class="nb">print</span> <span class="s2">&quot;Hello!&quot;</span>
</pre></div>

If we follow the pyg filter with the l filter (which does nothing, but it only accepts input of documents with .tex extension):

- hello.py|pyg|l

then pygments will output LaTeX markup instead:

\begin{Verbatim}[commandchars=\\\{\}]
\PY{n+nb}{print} \PY{l+s+s2}{\PYZdq{}}\PY{l+s+s2}{Hello!}\PY{l+s+s2}{\PYZdq{}}
\end{Verbatim}

Pygments will automatically determine which lexer to use based on the file extension of the incoming file. In the above examples, the .py file extension tells pygments that it should use the python lexer. If you need a different lexer than the default for the file extension, then you can pass a custom lexer argument:

- hello.txt|pyg:
    - pyg: { 'lexer' : 'python' }

You can see a list of all the available lexers, the file extensions they correspond to, and the aliases you can use to specify them, as follows:

$ pygmentize -L lexers
Pygments version 2.6.1, (c) 2006-2019 by Georg Brandl.

Lexers:
~~~~~~~
* abap:
    ABAP (filenames *.abap, *.ABAP)
* abnf:
    ABNF (filenames *.abnf)
* ada, ada95, ada2005:
    Ada (filenames *.adb, *.ads, *.ada)
* adl:
    ADL (filenames *.adl, *.adls, *.adlf, *.adlx)
* agda:
    Agda (filenames *.agda)

Dexy adds some custom file extension -> lexer mappings of its own, such as .pycon and .rbcon for python console and ruby console transcripts.

Custom formatter options can also be passed. Note that these options may be different for the HTMLFormatter and, say, the LatexFormatter. For information consult the Pygments Documentation for the formatter you are using. Here is an example of setting the noclasses attribute to True:

- hello.py|pyg|-noclasses:
    - pyg: { 'noclasses' : True }

And here is the resulting HTML:

<div class="highlight" style="background: #f8f8f8"><pre style="line-height: 125%"><span></span><a name="hello.py-pyg.html-1"></a><span style="color: #008000">print</span> <span style="color: #BA2121">&quot;Hello!&quot;</span>
</pre></div>

As a reminder here is the default HTML again:

<div class="highlight"><pre><span></span><a name="hello.py-pyg.html-1"></a><span class="nb">print</span> <span class="s2">&quot;Hello!&quot;</span>
</pre></div>

Pygments Image Examples

It is possible to generate image files from source code. Here is how to tell pygments to output a jpg:

- hello.py|pyg|jn

And here's a png, this time without line numbers and using a custom font:

- hello.py|pyg|pn:
    - pyg: { 'line_numbers' : False, 'font_name' : 'Source Code Pro' }

Here's a gif with the bw (black and white) style:

- hello.py|pyg|gn:
    - pyg: { 'style' : 'bw' }

Consult the Pygments Documentation for details about other options you can pass to these formatters.

Pygments Stylesheets Examples

The pygments filter applies syntax highlighting to source code. For HTML and LaTeX, the default pygments output wraps the code with a class or macro, and a stylesheet needs to be applied to actually colorize the output.

You can use the pygmentize command line tool to list available styles:

$ pygmentize -L styles
Pygments version 2.6.1, (c) 2006-2019 by Georg Brandl.

Styles:
~~~~~~~
* default:
    The default style (inspired by Emacs 22).
* emacs:
    The default style (inspired by Emacs 22).
* friendly:
    A modern style based on the VIM pyte theme.
* colorful:
    A colorful style, inspired by CodeRay.
* autumn:
    A colorful style, inspired by the terminal highlighting style.

to generate a CSS stylesheet for use with HTML:

$ pygmentize -S manni -f html > manni.css
$ head -n 5 manni.css
.hll { background-color: #ffffcc }
.c { color: #0099FF; font-style: italic } /* Comment */
.err { color: #AA0000; background-color: #FFAAAA } /* Error */
.k { color: #006699; font-weight: bold } /* Keyword */
.o { color: #555555 } /* Operator */

or to generate a .sty file for use with LaTeX:

$ pygmentize -S manni -f latex > manni.sty
$ head -n 5 manni.sty

\makeatletter
\def\PY@reset{\let\PY@it=\relax \let\PY@bf=\relax%
    \let\PY@ul=\relax \let\PY@tc=\relax%
    \let\PY@bc=\relax \let\PY@ff=\relax}

The pygments filter also has some built-in ways to get stylesheets in your project.

Any blank file ending in .css or .sty passed through the pyg filter will have stylesheet contents generated if the final output extension of the file is also set to .css or .sty:

- pastie.css|pyg:
    - pyg: { 'ext' : '.css' }
    - contents: ' '

Here is an excerpt from the generated stylesheet:

.hll { background-color: #ffffcc }
.c { color: #408080; font-style: italic } /* Comment */
.err { border: 1px solid #FF0000 } /* Error */
.k { color: #008000; font-weight: bold } /* Keyword */
.o { color: #666666 } /* Operator */
.ch { color: #408080; font-style: italic } /* Comment.Hashbang */
.cm { color: #408080; font-style: italic } /* Comment.Multiline */
.cp { color: #BC7A00 } /* Comment.Preproc */
.cpf { color: #408080; font-style: italic } /* Comment.PreprocFile */
.c1 { color: #408080; font-style: italic } /* Comment.Single */

Here is a LaTeX version:

- pastie.sty|pyg:
    - pyg: { 'ext' : '.sty' }
    - contents: ' '

Here is an excerpt from the generated .sty file:

\makeatletter
\def\PY@reset{\let\PY@it=\relax \let\PY@bf=\relax%
    \let\PY@ul=\relax \let\PY@tc=\relax%
    \let\PY@bc=\relax \let\PY@ff=\relax}
\def\PY@tok#1{\csname PY@tok@#1\endcsname}
\def\PY@toks#1+{\ifx\relax#1\empty\else%
    \PY@tok{#1}\expandafter\PY@toks\fi}
\def\PY@do#1{\PY@bc{\PY@tc{\PY@ul{%
    \PY@it{\PY@bf{\PY@ff{#1}}}}}}}

You can also insert style definitions directly into the header of a document. Jinja has a pygments object which contains entries for each of the avaliable pygments styles, for html or latex.

Here's an example of a HTML file which incorporates CSS and also lists the available styles:

<html>
    <head>
        <style type="text/css">

{{ pygments['pastie.css'] }}

        </style>
    </head>
    <body>
        <p>Here is a list of all the available stylesheets:</p>
        <ul>
            {% for k in sorted(pygments) -%}
            <li>{{ k }}</li>
            {% endfor -%}
        </ul>
    </body>
</html>

This is run by passing the html through the jinja filter:

- example.html|jinja

Here is the resulting HTML:

<html>
    <head>
        <style type="text/css">

.hll { background-color: #ffffcc }
.c { color: #888888 } /* Comment */
.err { color: #a61717; background-color: #e3d2d2 } /* Error */
.k { color: #008800; font-weight: bold } /* Keyword */
.ch { color: #888888 } /* Comment.Hashbang */
.cm { color: #888888 } /* Comment.Multiline */
.cp { color: #cc0000; font-weight: bold } /* Comment.Preproc */
.cpf { color: #888888 } /* Comment.PreprocFile */
.c1 { color: #888888 } /* Comment.Single */
.cs { color: #cc0000; font-weight: bold; background-color: #fff0f0 } /* Comment.Special */
.gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
.ge { font-style: italic } /* Generic.Emph */
.gr { color: #aa0000 } /* Generic.Error */
.gh { color: #333333 } /* Generic.Heading */
.gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
.go { color: #888888 } /* Generic.Output */
.gp { color: #555555 } /* Generic.Prompt */
.gs { font-weight: bold } /* Generic.Strong */
.gu { color: #666666 } /* Generic.Subheading */
.gt { color: #aa0000 } /* Generic.Traceback */
.kc { color: #008800; font-weight: bold } /* Keyword.Constant */
.kd { color: #008800; font-weight: bold } /* Keyword.Declaration */
.kn { color: #008800; font-weight: bold } /* Keyword.Namespace */
.kp { color: #008800 } /* Keyword.Pseudo */
.kr { color: #008800; font-weight: bold } /* Keyword.Reserved */
.kt { color: #888888; font-weight: bold } /* Keyword.Type */
.m { color: #0000DD; font-weight: bold } /* Literal.Number */
.s { color: #dd2200; background-color: #fff0f0 } /* Literal.String */
.na { color: #336699 } /* Name.Attribute */
.nb { color: #003388 } /* Name.Builtin */
.nc { color: #bb0066; font-weight: bold } /* Name.Class */
.no { color: #003366; font-weight: bold } /* Name.Constant */
.nd { color: #555555 } /* Name.Decorator */
.ne { color: #bb0066; font-weight: bold } /* Name.Exception */
.nf { color: #0066bb; font-weight: bold } /* Name.Function */
.nl { color: #336699; font-style: italic } /* Name.Label */
.nn { color: #bb0066; font-weight: bold } /* Name.Namespace */
.py { color: #336699; font-weight: bold } /* Name.Property */
.nt { color: #bb0066; font-weight: bold } /* Name.Tag */
.nv { color: #336699 } /* Name.Variable */
.ow { color: #008800 } /* Operator.Word */
.w { color: #bbbbbb } /* Text.Whitespace */
.mb { color: #0000DD; font-weight: bold } /* Literal.Number.Bin */
.mf { color: #0000DD; font-weight: bold } /* Literal.Number.Float */
.mh { color: #0000DD; font-weight: bold } /* Literal.Number.Hex */
.mi { color: #0000DD; font-weight: bold } /* Literal.Number.Integer */
.mo { color: #0000DD; font-weight: bold } /* Literal.Number.Oct */
.sa { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Affix */
.sb { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Backtick */
.sc { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Char */
.dl { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Delimiter */
.sd { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Doc */
.s2 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Double */
.se { color: #0044dd; background-color: #fff0f0 } /* Literal.String.Escape */
.sh { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Heredoc */
.si { color: #3333bb; background-color: #fff0f0 } /* Literal.String.Interpol */
.sx { color: #22bb22; background-color: #f0fff0 } /* Literal.String.Other */
.sr { color: #008800; background-color: #fff0ff } /* Literal.String.Regex */
.s1 { color: #dd2200; background-color: #fff0f0 } /* Literal.String.Single */
.ss { color: #aa6600; background-color: #fff0f0 } /* Literal.String.Symbol */
.bp { color: #003388 } /* Name.Builtin.Pseudo */
.fm { color: #0066bb; font-weight: bold } /* Name.Function.Magic */
.vc { color: #336699 } /* Name.Variable.Class */
.vg { color: #dd7700 } /* Name.Variable.Global */
.vi { color: #3333bb } /* Name.Variable.Instance */
.vm { color: #336699 } /* Name.Variable.Magic */
.il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */

        </style>
    </head>
    <body>
        <p>Here is a list of all the available stylesheets:</p>
        <ul>
            <li>abap.css</li>
            <li>abap.html</li>
            <li>abap.tex</li>
            <li>algol.css</li>
            <li>algol.html</li>
            <li>algol.tex</li>
            <li>algol_nu.css</li>
            <li>algol_nu.html</li>
            <li>algol_nu.tex</li>
            <li>arduino.css</li>
            <li>arduino.html</li>
            <li>arduino.tex</li>
            <li>autumn.css</li>
            <li>autumn.html</li>
            <li>autumn.tex</li>
            <li>borland.css</li>
            <li>borland.html</li>
            <li>borland.tex</li>
            <li>bw.css</li>
            <li>bw.html</li>
            <li>bw.tex</li>
            <li>colorful.css</li>
            <li>colorful.html</li>
            <li>colorful.tex</li>
            <li>default.css</li>
            <li>default.html</li>
            <li>default.tex</li>
            <li>emacs.css</li>
            <li>emacs.html</li>
            <li>emacs.tex</li>
            <li>friendly.css</li>
            <li>friendly.html</li>
            <li>friendly.tex</li>
            <li>fruity.css</li>
            <li>fruity.html</li>
            <li>fruity.tex</li>
            <li>igor.css</li>
            <li>igor.html</li>
            <li>igor.tex</li>
            <li>inkpot.css</li>
            <li>inkpot.html</li>
            <li>inkpot.tex</li>
            <li>lovelace.css</li>
            <li>lovelace.html</li>
            <li>lovelace.tex</li>
            <li>manni.css</li>
            <li>manni.html</li>
            <li>manni.tex</li>
            <li>monokai.css</li>
            <li>monokai.html</li>
            <li>monokai.tex</li>
            <li>murphy.css</li>
            <li>murphy.html</li>
            <li>murphy.tex</li>
            <li>native.css</li>
            <li>native.html</li>
            <li>native.tex</li>
            <li>paraiso-dark.css</li>
            <li>paraiso-dark.html</li>
            <li>paraiso-dark.tex</li>
            <li>paraiso-light.css</li>
            <li>paraiso-light.html</li>
            <li>paraiso-light.tex</li>
            <li>pastie.css</li>
            <li>pastie.html</li>
            <li>pastie.tex</li>
            <li>perldoc.css</li>
            <li>perldoc.html</li>
            <li>perldoc.tex</li>
            <li>rainbow_dash.css</li>
            <li>rainbow_dash.html</li>
            <li>rainbow_dash.tex</li>
            <li>rrt.css</li>
            <li>rrt.html</li>
            <li>rrt.tex</li>
            <li>sas.css</li>
            <li>sas.html</li>
            <li>sas.tex</li>
            <li>solarized-dark.css</li>
            <li>solarized-dark.html</li>
            <li>solarized-dark.tex</li>
            <li>solarized-light.css</li>
            <li>solarized-light.html</li>
            <li>solarized-light.tex</li>
            <li>stata-dark.css</li>
            <li>stata-dark.html</li>
            <li>stata-dark.tex</li>
            <li>stata-light.css</li>
            <li>stata-light.html</li>
            <li>stata-light.tex</li>
            <li>stata.css</li>
            <li>stata.html</li>
            <li>stata.tex</li>
            <li>tango.css</li>
            <li>tango.html</li>
            <li>tango.tex</li>
            <li>trac.css</li>
            <li>trac.html</li>
            <li>trac.tex</li>
            <li>vim.css</li>
            <li>vim.html</li>
            <li>vim.tex</li>
            <li>vs.css</li>
            <li>vs.html</li>
            <li>vs.tex</li>
            <li>xcode.css</li>
            <li>xcode.html</li>
            <li>xcode.tex</li>
            </ul>
    </body>
</html>