Pygments for WordPress

This plugin uses pygments to highlight code on the server, with a simple shortcode. For example, [pygmentize language=”python”]print “Hello”[/pygmentize], or use the shorter code, [pyg].

[pyg language="python" style="monokai" linenos="table" hl_lines="7 8 9" ]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
#
# Here is some raw Python, pasted directly into the page:
#

# For every line...
for line in lines:
	# ...print it out if it's not blank:
	if line != "":
		print line
	else:
		result = blank_line_handler()
		print "Blank line found, handler returned: %s" % result
[/pyg]

Description

This WordPress plugin is a syntax highlighter for many different computer languages, including HTML, Python, PHP, Javascript, CSS, and many others. It uses the Pygments syntax highlighter from Python. It calls the pygmentize command on the server, so most of the features come directly from that command.

You can paste raw code directly from your source code editor into your WordPress pages or posts, and by wrapping it with [pyg] shortcode tags, it will appear syntax highlighted in your pages.

Features

  • Line numbers are optional, using both an HTML table (which lets you copy’n'paste code from the page without any line numbers embedded), and alternatively “inline” line numbers, so that they are included when copy’n'pasting from the screen.
  • Tabs are preserved, and you can use a customizable tab width! (The examples here use a width of 4 spaces. Copy’n'paste it someplace to see!)
  • Extra “bright” highlighting of arbitrary line numbers is supported, by specifying which line numbers you want to draw attention to.
  • Server-side highlighting. In contrast to the older SyntaxHighlighter or SyntaxHighlighter Evolved plugins, this library does the syntax highlighting on the server, not in the web browser. It uses only CSS markup and HTML, and no Javascript.
  • Full Pygments support: 197 languages (incl. combos like HTML+PHP), and 18 colorful styles. Each block of code can have its own style. The older Javascript plugins mentioned above only support 23 languages, and 7 styles.
  • Unlike WpPygments, this plugin does not communicate with any remote web services. It runs the pygmentize command on the server instead.
  • This plugin may be installed in parallel with the other syntax highlighter plugins, because they don’t use the [pyg] shortcode.
  • Just ~320 lines of PHP code, and about a third of that is license and comments.
  • Works with the Visual editor enabled, however, note that the Visual editor will mess up whitespace, esp. tabs. So using the editor in HTML mode is strongly recommended.)
  • As a convenience feature, the shortcode options for language, style, tabwidth, linenos, and nowrap are remembered after each call. So you only need to specify them once, for the first code block. Then they become the defaults for the rest of the page.
  • Based on the library Pygments for PHP and the shortcode processor in the RawR (Raw Revisited) WordPress plug-in

Installation

This plugin depends on the command pygmentize being in the web server’s path. With Ubuntu or Debian,
this can be achieved by typing

sudo apt-get install python-pygments

After that, install this plugin like any other.

Download it from the WordPress.org Plugin repository:

http://downloads.wordpress.org/plugin/pygments-for-wordpress.zip

Then go to Admin > Plugins > Add New > Upload.

If that’s too easy for you, try this:

1. Put it into `/wp-content/plugins/` directory
2. Activate it in the admin Plugin page.

Usage

Here are some examples:

[pygmentize language="python"]
# For every line...
for line in lines:
	# ...print it out if it's not blank:
	if line != "":
		print line
	else:
		result = blank_line_handler()
		print "Blank line found, handler returned: %s" % result
[/pygmentize]

 

Typing in “pygmentize” gets tedious, so you can use [pyg] for short:

[pyg language="html+php" style="monokai" ]
<H2 class="sample" >Some HTML</H2>
<?php
		if ( $hl_lines != NULL ) {
			/* We split apart the passed-in arg to make sure each one is numeric: */
			$hl_lines_array = preg_split( '/ +/', $hl_lines );
			$hl_lines_array_safe = array();

			foreach ( $hl_lines_array as $line_no ) {
					if ( is_numeric( $line_no ) ) {
					$hl_lines_array_safe[] = $line_no;
				}
			}
			$option = "hl_lines='" . join(" ", $hl_lines_array_safe ) . "'";
			$extra_opts_array[] = $option;
		}
[/pyg]

 
You can also use the short form ‘l’ and ‘s’ to for the common options ‘language’ and ‘style’:

[pyg l="ruby" s="colorful" ]
#!/usr/bin/ruby
presidents = ["Ford", "Carter", "Reagan", "Bush1", "Clinton", "Bush2"]
for ss in 0...presidents.length
	print ss, ": ", presidents[presidents.length - ss - 1], "\n";
end
[/pyg]

 
[pyg l="bbcode" tabwidth="3" s="emacs" ]
Linking to a named site:
	[url=http://www.bbcode.org/]This be bbcode.org![/url]
[/pyg]

 
You can get an instant preview of various styles by using the official Pygments Demo page.

The following attributes are available. See the pygmentize documentation for more details about these options:

  • language, l

    Which of the ~197 language syntaxes you’d like to highlight in. Common examples are “python”, “php”, “html+php”, “css”, “js”. See the full list by running “pygmentize -L” on your server, or check the list at the end of this page.

  • style, s

    Which of the 18 color styles you’d like to highlight in. See the full list by running “pygmentize -L” on your server, or check the list at the end of this page.

  • tabwidth

    The number of character widths to render tabs as. The default is 4 chars.

  • linenos

    Whether or not to display line numbers. This can be empty, like linenos=”", to turn off line numbering. It can be set to “inline”, or “table”. Inline numbers are inserted into the code lines, but table uses a separate table column for the numbers. The “table” option allows users to easily copy’n'paste working code from your web page, even though it is annotated with line numbers.

  • linenostart

    When using linenos, you can have the line numbers start with a number higher than 1. This is useful for referencing line numbers in a file. Example: linenostart=”57″

  • hl_lines

    In addition to regular syntax highlighting, you can also “highlight” specific lines to stand out above the regular code. Just specify a space-separated list of numbers, like: hl_lines=”42 43 68 69″

  • nowrap

    If set to True, don’t wrap the tokens in any HTML tags at all, not even inside a <pre> tag. (This has nothing to do with line wrapping. It’s for getting raw tokenized output.) See the pygmentize docs for details.

The following attribrutes are remembered each call, so you only need to specify them for your first block of code (and then they are the defaults for the rest of the page or post), which saves typing if your pages contain all the same type of highlighted code:

  • language
  • style
  • tabwidth
  • linenos
  • nowrap

For example, if you highlight some code with these options:

[pyg l="python" s="monokai" linenos="table" linenostart="54" nowrap="True"] ... [/pyg]

Now any subsequent calls on this page (or post) will default to python, with line numbers, in the monokai style:

[pyg] ...this gets rendered as python in the monokai colors, with line numbers... [/pyg]
[pyg hl_lines="3 4 7"] ...same here... [/pyg]

 

Styles and Languages Available (YMMV)

derek@derek-laptop:~$ pygmentize -L
Pygments version 1.2.2, (c) 2006-2008 by Georg Brandl.

Lexers:
~~~~~~~
* Cucumber, cucumber, Gherkin, gherkin:
    Gherkin (filenames *.feature)
* abap:
    ABAP (filenames *.abap)
* antlr-as, antlr-actionscript:
    ANTLR With ActionScript Target (filenames *.G, *.g)
* antlr-cpp:
    ANTLR With CPP Target (filenames *.G, *.g)
* antlr-csharp, antlr-c#:
    ANTLR With C# Target (filenames *.G, *.g)
* antlr-java:
    ANTLR With Java Target (filenames *.G, *.g)
* antlr-objc:
    ANTLR With ObjectiveC Target (filenames *.G, *.g)
* antlr-perl:
    ANTLR With Perl Target (filenames *.G, *.g)
* antlr-python:
    ANTLR With Python Target (filenames *.G, *.g)
* antlr-ruby, antlr-rb:
    ANTLR With Ruby Target (filenames *.G, *.g)
* antlr:
    ANTLR
* apacheconf, aconf, apache:
    ApacheConf (filenames .htaccess, apache.conf, apache2.conf)
* applescript:
    AppleScript (filenames *.applescript)
* as, actionscript:
    ActionScript (filenames *.as)
* as3, actionscript3:
    ActionScript 3 (filenames *.as)
* aspx-cs:
    aspx-cs (filenames *.aspx, *.asax, *.ascx, *.ashx, *.asmx, *.axd)
* aspx-vb:
    aspx-vb (filenames *.aspx, *.asax, *.ascx, *.ashx, *.asmx, *.axd)
* asy:
    Asymptote (filenames *.asy)
* basemake:
    Makefile
* bash, sh:
    Bash (filenames *.sh, *.ebuild, *.eclass)
* bat:
    Batchfile (filenames *.bat, *.cmd)
* bbcode:
    BBCode
* befunge:
    Befunge (filenames *.befunge)
* boo:
    Boo (filenames *.boo)
* brainfuck, bf:
    Brainfuck (filenames *.bf, *.b)
* c-objdump:
    c-objdump (filenames *.c-objdump)
* c:
    C (filenames *.c, *.h)
* cheetah, spitfire:
    Cheetah (filenames *.tmpl, *.spt)
* clojure, clj:
    Clojure (filenames *.clj)
* cmake:
    CMake (filenames *.cmake)
* common-lisp, cl:
    Common Lisp (filenames *.cl, *.lisp, *.el)
* console:
    Bash Session (filenames *.sh-session)
* control:
    Debian Control file (filenames control)
* cpp, c++:
    C++ (filenames *.cpp, *.hpp, *.c++, *.h++, *.cc, *.hh, *.cxx, *.hxx)
* cpp-objdump, c++-objdumb, cxx-objdump:
    cpp-objdump (filenames *.cpp-objdump, *.c++-objdump, *.cxx-objdump)
* csharp, c#:
    C# (filenames *.cs)
* css+django, css+jinja:
    CSS+Django/Jinja
* css+erb, css+ruby:
    CSS+Ruby
* css+genshitext, css+genshi:
    CSS+Genshi Text
* css+mako:
    CSS+Mako
* css+mako:
    CSS+Mako
* css+myghty:
    CSS+Myghty
* css+php:
    CSS+PHP
* css+smarty:
    CSS+Smarty
* css:
    CSS (filenames *.css)
* cython, pyx:
    Cython (filenames *.pyx, *.pxd, *.pxi)
* d-objdump:
    d-objdump (filenames *.d-objdump)
* d:
    D (filenames *.d, *.di)
* delphi, pas, pascal, objectpascal:
    Delphi (filenames *.pas)
* diff, udiff:
    Diff (filenames *.diff, *.patch)
* django, jinja:
    Django/Jinja
* dpatch:
    Darcs Patch (filenames *.dpatch, *.darcspatch)
* dylan:
    Dylan (filenames *.dylan)
* erb:
    ERB
* erl:
    Erlang erl session (filenames *.erl-sh)
* erlang:
    Erlang (filenames *.erl, *.hrl)
* evoque:
    Evoque (filenames *.evoque)
* fortran:
    Fortran (filenames *.f, *.f90)
* gas:
    GAS (filenames *.s, *.S)
* genshi, kid, xml+genshi, xml+kid:
    Genshi (filenames *.kid)
* genshitext:
    Genshi Text
* glsl:
    GLSL (filenames *.vert, *.frag, *.geo)
* gnuplot:
    Gnuplot (filenames *.plot, *.plt)
* go:
    Go (filenames *.go)
* groff, nroff, man:
    Groff (filenames *.[1234567], *.man)
* haskell, hs:
    Haskell (filenames *.hs)
* html+cheetah, html+spitfire:
    HTML+Cheetah
* html+django, html+jinja:
    HTML+Django/Jinja
* html+evoque:
    HTML+Evoque (filenames *.html)
* html+genshi, html+kid:
    HTML+Genshi
* html+mako:
    HTML+Mako
* html+mako:
    HTML+Mako
* html+myghty:
    HTML+Myghty
* html+php:
    HTML+PHP (filenames *.phtml)
* html+smarty:
    HTML+Smarty
* html:
    HTML (filenames *.html, *.htm, *.xhtml, *.xslt)
* ini, cfg:
    INI (filenames *.ini, *.cfg, *.properties)
* io:
    Io (filenames *.io)
* irc:
    IRC logs (filenames *.weechatlog)
* java:
    Java (filenames *.java)
* js+cheetah, javascript+cheetah, js+spitfire, javascript+spitfire:
    JavaScript+Cheetah
* js+django, javascript+django, js+jinja, javascript+jinja:
    JavaScript+Django/Jinja
* js+erb, javascript+erb, js+ruby, javascript+ruby:
    JavaScript+Ruby
* js+genshitext, js+genshi, javascript+genshitext, javascript+genshi:
    JavaScript+Genshi Text
* js+mako, javascript+mako:
    JavaScript+Mako
* js+mako, javascript+mako:
    JavaScript+Mako
* js+myghty, javascript+myghty:
    JavaScript+Myghty
* js+php, javascript+php:
    JavaScript+PHP
* js+smarty, javascript+smarty:
    JavaScript+Smarty
* js, javascript:
    JavaScript (filenames *.js)
* jsp:
    Java Server Page (filenames *.jsp)
* lhs, literate-haskell:
    Literate Haskell (filenames *.lhs)
* lighty, lighttpd:
    Lighttpd configuration file
* llvm:
    LLVM (filenames *.ll)
* logtalk:
    Logtalk (filenames *.lgt)
* lua:
    Lua (filenames *.lua)
* make, makefile, mf, bsdmake:
    Makefile (filenames *.mak, Makefile, makefile, Makefile.*, GNUmakefile)
* mako:
    Mako (filenames *.mao)
* mako:
    Mako (filenames *.mao)
* matlab, octave:
    Matlab (filenames *.m)
* matlabsession:
    Matlab session
* minid:
    MiniD (filenames *.md)
* modelica:
    Modelica (filenames *.mo)
* moocode:
    MOOCode (filenames *.moo)
* mupad:
    MuPAD (filenames *.mu)
* mxml:
    MXML (filenames *.mxml)
* myghty:
    Myghty (filenames *.myt, autodelegate)
* mysql:
    MySQL
* nasm:
    NASM (filenames *.asm, *.ASM)
* newspeak:
    Newspeak (filenames *.ns2)
* nginx:
    Nginx configuration file
* numpy:
    NumPy
* objdump:
    objdump (filenames *.objdump)
* objective-c, objectivec, obj-c, objc:
    Objective-C (filenames *.m)
* ocaml:
    OCaml (filenames *.ml, *.mli, *.mll, *.mly)
* ooc:
    Ooc (filenames *.ooc)
* perl, pl:
    Perl (filenames *.pl, *.pm)
* php, php3, php4, php5:
    PHP (filenames *.php, *.php[345])
* pot, po:
    Gettext Catalog (filenames *.pot, *.po)
* pov:
    POVRay (filenames *.pov, *.inc)
* prolog:
    Prolog (filenames *.prolog, *.pro, *.pl)
* py3tb:
    Python 3.0 Traceback (filenames *.py3tb)
* pycon:
    Python console session
* pytb:
    Python Traceback (filenames *.pytb)
* python, py:
    Python (filenames *.py, *.pyw, *.sc, SConstruct, SConscript)
* python3, py3:
    Python 3
* ragel-c:
    Ragel in C Host (filenames *.rl)
* ragel-cpp:
    Ragel in CPP Host (filenames *.rl)
* ragel-d:
    Ragel in D Host (filenames *.rl)
* ragel-em:
    Embedded Ragel (filenames *.rl)
* ragel-java:
    Ragel in Java Host (filenames *.rl)
* ragel-objc:
    Ragel in Objective C Host (filenames *.rl)
* ragel-ruby, ragel-rb:
    Ragel in Ruby Host (filenames *.rl)
* ragel:
    Ragel
* raw:
    Raw token data
* rb, ruby:
    Ruby (filenames *.rb, *.rbw, Rakefile, *.rake, *.gemspec, *.rbx)
* rbcon, irb:
    Ruby irb session
* rebol:
    REBOL (filenames *.r, *.r3)
* redcode:
    Redcode (filenames *.cw)
* rhtml, html+erb, html+ruby:
    RHTML (filenames *.rhtml)
* rst, rest, restructuredtext:
    reStructuredText (filenames *.rst, *.rest)
* scala:
    Scala (filenames *.scala)
* scheme, scm:
    Scheme (filenames *.scm)
* smalltalk, squeak:
    Smalltalk (filenames *.st)
* smarty:
    Smarty (filenames *.tpl)
* sourceslist, sources.list:
    Debian Sourcelist (filenames sources.list)
* splus, s, r:
    S (filenames *.S, *.R)
* sql:
    SQL (filenames *.sql)
* sqlite3:
    sqlite3con (filenames *.sqlite3-console)
* squidconf, squid.conf, squid:
    SquidConf (filenames squid.conf)
* tcl:
    Tcl (filenames *.tcl)
* tcsh, csh:
    Tcsh (filenames *.tcsh, *.csh)
* tex, latex:
    TeX (filenames *.tex, *.aux, *.toc)
* text:
    Text only (filenames *.txt)
* trac-wiki, moin:
    MoinMoin/Trac Wiki markup
* vala, vapi:
    Vala (filenames *.vala, *.vapi)
* vb.net, vbnet:
    VB.net (filenames *.vb, *.bas)
* vim:
    VimL (filenames *.vim, .vimrc)
* xml+cheetah, xml+spitfire:
    XML+Cheetah
* xml+django, xml+jinja:
    XML+Django/Jinja
* xml+erb, xml+ruby:
    XML+Ruby
* xml+evoque:
    XML+Evoque (filenames *.xml)
* xml+mako:
    XML+Mako
* xml+mako:
    XML+Mako
* xml+myghty:
    XML+Myghty
* xml+php:
    XML+PHP
* xml+smarty:
    XML+Smarty
* xml:
    XML (filenames *.xml, *.xsl, *.rss, *.xslt, *.xsd, *.wsdl)
* xslt:
    XSLT (filenames *.xsl, *.xslt)
* yaml:
    YAML (filenames *.yaml, *.yml)

[...other docs snipped...]

Styles:
~~~~~~~
* monokai:
    This style mimics the Monokai color scheme.
* manni:
    A colorful style, inspired by the terminal highlighting style.
* perldoc:
    Style similar to the style used in the perldoc code blocks.
* borland:
    Style similar to the style used in the borland IDEs.
* colorful:
    A colorful style, inspired by CodeRay.
* default:
    The default style (inspired by Emacs 22).
* murphy:
    Murphy's style from CodeRay.
* vs:

* trac:
    Port of the default trac highlighter design.
* tango:
    The Crunchy default Style inspired from the color palette from the Tango Icon Theme Guidelines.
* fruity:
    Pygments version of the "native" vim theme.
* autumn:
    A colorful style, inspired by the terminal highlighting style.
* bw:

* emacs:
    The default style (inspired by Emacs 22).
* pastie:
    Style similar to the pastie default style.
* friendly:
    A modern style based on the VIM pyte theme.
* native:
    Pygments version of the "native" vim theme.

Comments are closed.