Pygments

Available formatters

« Back To Index

Contents

This page lists all builtin formatters.

Common options

The HtmlFormatter and LatexFormatter classes support these options:

style
The style to use, can be a string or a Style subclass (default: 'default').
full
Tells the formatter to output a "full" document, i.e. a complete self-contained document (default: False).
title
If full is true, the title that should be used to caption the document (default: '').
linenos
If set to True, output line numbers (default: False).
linenostart
The line number for the first line (default: 1).
linenostep
If set to a number n > 1, only every nth line number is printed.

Formatter classes

All these classes are importable from pygments.formatters.

HtmlFormatter

Formats tokens as HTML 4 <span> tags within a <pre> tag, wrapped in a <div> tag. The <div>'s CSS class can be set by the cssclass option.

If the linenos option is given and true, the <pre> is additionally wrapped inside a <table> which has one row and two cells: one containing the line numbers and one containing the code. Example:

<div class="highlight" >
<table><tr>
  <td class="linenos" title="click to toggle"
    onclick="with (this.firstChild.style)
             { display = (display == '') ? 'none' : '' }">
    <pre>1
    2</pre>
  </td>
  <td class="code">
    <pre><span class="Ke">def </span><span class="NaFu">foo</span>(bar):
      <span class="Ke">pass</span>
    </pre>
  </td>
</tr></table></div>

(whitespace added to improve clarity). Wrapping can be disabled using the nowrap option.

With the full option, a complete HTML 4 document is output, including the style definitions inside a <style> tag.

The get_style_defs(arg='') method of a HtmlFormatter returns a string containing CSS rules for the CSS classes used by the formatter. The argument arg can be used to specify additional CSS selectors that are prepended to the classes. A call fmter.get_style_defs('td .code') would result in the following CSS classes:

td .code .kw { font-weight: bold; color: #00FF00 }
td .code .cm { color: #999999 }
...

Additional options accepted by the HtmlFormatter:

nowrap
If set to True, don't wrap the tokens at all, not even in a <pre> tag. This disables all other options (default: False).
noclasses
If set to true, token <span> tags will not use CSS classes, but inline styles. This is not recommended for larger pieces of code since it increases output size by quite a bit (default: False).
classprefix
Since the token types use relatively short class names, they may clash with some of your own class names. In this case you can use the classprefix option to give a string to prepend to all Pygments-generated CSS class names for token types. Note that this option also affects the output of get_style_defs().
cssclass
CSS class for the wrapping <div> tag (default: 'highlight').
cssstyles
Inline CSS styles for the wrapping <div> tag (default: '').
linenospecial
If set to a number n > 0, every nth line number is given the CSS class "special" (default: 0).
Aliases:html
Filename patterns:*.html, *.htm

LatexFormatter

Formats tokens as LaTeX code. This needs the fancyvrb and color standard packages.

Without the full option, code is formatted as one Verbatim environment, like this:

\begin{Verbatim}[commandchars=@\[\]]
@Can[def ]@Cax[foo](bar):
    @Can[pass]
\end{Verbatim}

The command sequences used here (@Can etc.) are generated from the given style and can be retrieved using the get_style_defs method.

With the full option, a complete LaTeX document is output, including the command definitions in the preamble.

The get_style_defs(arg='') method of a LatexFormatter returns a string containing \newcommand commands defining the commands used inside the Verbatim environments. If the argument arg is true, \renewcommand is used instead.

Additional options accepted by the LatexFormatter:

docclass
If the full option is enabled, this is the document class to use (default: 'article').
preamble
If the full option is enabled, this can be further preamble commands, e.g. \usepackage (default: '').
verboptions
Additional options given to the Verbatim environment (see the fancyvrb docs for possible values) (default: '').
Aliases:latex, tex
Filename pattern:*.tex

BBCodeFormatter

Formats tokens with BBcodes. These formatting codes are used by many bulletin boards, so you can highlight your sourcecode with pygments before posting it there.

This formatter has no support for background colors and borders, as there are no common BBcode tags for that.

Some board systems (e.g. phpBB) don't support colors in their [code] tag, so you can't use the highlighting together with that tag. Text in a [code] tag usually is shown with a monospace font (which this formatter can do with the monofont option) and no spaces (which you need for indentation) are removed.

The BBCodeFormatter accepts two additional option:

codetag
If set to true, put the output into [code] tags (default: false)
monofont
If set to true, add a tag to show the code with a monospace font (default: false).
Aliases:bbcode, bb
Filename pattern:None

TerminalFormatter

Formats tokens with ANSI color sequences, for output in a text console. Color sequences are terminated at newlines, so that paging the output works correctly.

The get_style_defs() method doesn't do anything special since there is no support for common styles.

The TerminalFormatter class supports only these options:

bg
Set to "light" or "dark" depending on the terminal's background (default: "light").
colorscheme
A dictionary mapping token types to (lightbg, darkbg) color names or None (default: None = use builtin colorscheme).
debug
If this option is true, output the string "<<ERROR>>" after each error token. This is meant as a help for debugging Pygments (default: False).
Aliases:terminal, console
Filename pattern:None

RawTokenFormatter

Formats tokens as a raw representation for storing token streams.

The format is tokentype<TAB>repr(tokenstring)\n. The output can later be converted to a token stream with the RawTokenLexer, described in the lexer list.

One option is accepted:

compress
If set to 'gz' or 'bz2', compress the output with the given compression algorithm after encoding (default: '').
Aliases:raw, tokens
Filename pattern:*.raw

NullFormatter

Just output all tokens, don't format in any way.

Aliases:text, null
Filename pattern:*.txt