1   Syntax Highlight


Günter Milde




$Date: 2012-05-09 13:42:58 +0000 (Wed, 09 May 2012) $


© 2007, 2009, 2012 G. Milde,


Released under the terms of the 2-Clause BSD license, in short:

Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. This file is offered as-is, without any warranty.

Abstract:Proposal to add syntax highlight of code blocks to the capabilities of Docutils.

Syntax highlighting significantly enhances the readability of code. Since version 0.9, docutils supports this with a code directive and role as well as a code option to the include directive using the Pygments syntax highlighter.


The content of the following directive

.. code:: python

 def my_function():
     "just a test"
     print 8/2

is parsed and marked up as Python source code. The actual rendering depends on the style-sheet.

2   TODO

2.1   Configurable literal block directive

2.1.1   Goal

A clean and simple syntax for highlighted code blocks -- preserving the space saving feature of the "minimised" literal block marker (:: at the end of a text paragraph). This is especially desirable in documents with many code blocks like tutorials or literate programs.

2.1.2   Inline analogon

The role of inline interpreted text can be customised with the "default-role" directive. This allows the use of the concise "backtick" syntax for the most often used role, e.g. in a chemical paper, one could use:

.. default-role:: subscript

The triple point of H\ `2`\O is at 0°C.

to produce

The triple point of H2O is at 0°C.

This customisation is currently not possible for block markup.

2.1.3   Proposal

  • Define a new "literal-block" directive syntax for an ordinary literal block. This would simply insert the block content into the document tree as "literal-block" element.
  • Define a "default-literal-block" setting that controls which directive is called on a block following ::. Default would be the "literal-block" directive (backwards compatible).

2.1.4   Motivation

Analogue to customising the default role of "interpreted text" with the "default-role" directive, the concise :: literal-block markup could be used for e.g.

  • a "code-block" directive for syntax highight
  • the "line-block" directive for poems or addresses
  • the "parsed-literal" directive


ordinary literal block::

   some text typeset in monospace

.. default-literal-block::  code-block python

this is colourful Python code::

   def hello():
       print "hello world"

In the same line, a "default-block-quote" setting or directive could be considered to configure the role of a block quote.