Code blocks with syntax highlighting

Quick Reference

  • To insert a snippet as code with syntax highlighting, use the code-block directive or the shorthand ::.
  • You can explicitly set the language in the code-block, you cannot in the shorthand.
  • If you do not explicitly set the language, the default language (as set with the Highlight directive) is used. If no highlight directive was used, the default set in /Includes.rst.txt is used.
  • It is recommended to use the short form (::) instead of code-block explicitly.
  • Always use syntactically correct code in a code block.
  • Use placeholders in angle brackets (<placeholder-name>) to refer to a place in the code where you don’t care about the exact value.

The following examples all do the same thing:

  1. Use the shorthand :: (recommended):

    See following example::
    
       $a = 'b';
    
    How this looks:

    See following example:

    $a = 'b';
    

    You can use this, if the default language is already set to PHP with the highlight directive in the current file (or in Includes.rst.txt).

  2. Set the language (PHP) in the code-block:

    See following example:
    
    .. code-block:: php
    
       $a = 'b';
    
  3. Use code-block without setting the language:

    See following example:
    
    .. code-block::
    
       $a = 'b';
    

    You can use this, if you already set the language PHP with the highlight directive in the current file (or in Includes.rst.txt).

See also

Add a diagram to your code to enrich your documentation and provide a broader view on your solution.

Code block directive

Use codeblock with language PHP:

.. code-block:: php

   $a = 'b';

Use codeblock without specifying language:

.. code-block::

   $a = 'b';

This uses whatever language has last been set with the Highlight directive in the current file or in Includes.rst.txt.

Use syntactically correct code

Attention

Please: No syntax errors!

Syntax highlighting only works if the lexer can parse the code without errors. In other words: If there’s a syntax error in the code the highlighting will not work.

Wrong:

.. code-block:: php

   $a = array(
      'one' => 1,
      ...
   );

Correct:

.. code-block:: php

   $a = array(
      'one' => 1,
      // ...
   );

Sphinx uses Pygments for highlighting. On a machine that has Pygments installed the command pygmentize -L will list all available lexers.

Highlight directive

You can set the default language with the highlight directive. All following code blocks will use the language as specified in the highlight directive for syntax highlighting.

If all of your code blocks in one file have the same language, it is easier to just set this once at the beginning of the file.

This way, you don’t need to set the language for each code-block (.. code-block:: LANG) explicitly and can use the shorthand notation.

Use reStructuredText highlighting:

.. highlight:: rst

Use PHP highlighting:

.. highlight:: php

For TYPO3 we have adopted the convention that each reStructuredText source file imports the Documentation/Includes.rst.txt file at the top. And in the included file - in general - we set PHP as default language for highlighting. Exception: In the TypoScript manuals we are using typoscript as default.

You can use the ..highlight:: LANG directive as often as you want. Each one remains valid up to the next or up to the end of the single file it is used in.

Highlight language ‘guess’

Note that there is a - pseudo - language ‘guess’ as well. This should use the highlighter for the first language that Pygments finds to have no syntax error.

Highlight language ‘none’

The pseudo language ‘none’ is recognized as well. In this case no highlighting will occur.

Some more examples

Add line numbers to code snippet

Source

.. code-block:: php
   :linenos:

       $GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields'] .= ',tx_realurl_pathsegment';

       // Adjust to your needs
       $domain = 'example.org';
       $rootPageUid = 123;
       $rssFeedPageType = 9818; // pageType of your RSS feed page

Result

1
2
3
4
5
6
7
8
    <?php

    $GLOBALS['TYPO3_CONF_VARS']['FE']['addRootLineFields'] .= ',tx_realurl_pathsegment';

    // Adjust to your needs
    $domain = 'example.org';
    $rootPageUid = 123;
    $rssFeedPageType = 9818; // pageType of your RSS feed page

Turn off highlighting: Method 1

Source:

A description:

.. code-block:: none

   $ tree vendor/composer
   ├── ClassLoader.php
   ├── LICENSE
   ├── autoload_classmap.php
   ├── ...
   └── installed.json

Result

A description:

$ tree vendor/composer
├── ClassLoader.php
├── LICENSE
├── autoload_classmap.php
├── ...
└── installed.json

Turn off highlighting: Method 2

Source:

.. highlight:: none

A description::

   $ tree vendor/composer
   ├── ClassLoader.php
   ├── LICENSE
   ├── autoload_classmap.php
   ├── ...
   └── installed.json

Result

A description:

$ tree vendor/composer
├── ClassLoader.php
├── LICENSE
├── autoload_classmap.php
├── ...
└── installed.json

Available lexers

You can use any of the following names of lexers:

| bash, sh, ksh, shell | for example all mean the same lexer:

abap | abnf | ada, ada95, ada2005 | adl | agda | ahk, autohotkey | alloy | ampl | antlr-as, antlr-actionscript | antlr-cpp | antlr-csharp, antlr-c# | antlr-java | antlr-objc | antlr-perl | antlr-python | antlr-ruby, antlr-rb | antlr | apacheconf, aconf, apache | apl | applescript | arduino | as, actionscript | as3, actionscript3 | aspectj | aspx-cs | aspx-vb | asy, asymptote | at, ambienttalk, ambienttalk/2 | autoit | awk, gawk, mawk, nawk | basemake | bash, sh, ksh, shell | bat, batch, dosbatch, winbatch | bbcode | bc | befunge | blitzbasic, b3d, bplus | blitzmax, bmax | bnf | boo | boogie | brainfuck, bf | bro | bugs, winbugs, openbugs | c-objdump | c | ca65 | cadl | camkes, idl4 | cbmbas | ceylon | cfc | cfengine3, cf3 | cfm | cfs | chai, chaiscript | chapel, chpl | cheetah, spitfire | cirru | clay | clean | clojure, clj | clojurescript, cljs | cmake | cobol | cobolfree | coffee-script, coffeescript, coffee | common-lisp, cl, lisp | componentpascal, cp | console, shell-session | control, debcontrol | coq | cpp, c++ | cpp-objdump, c++-objdumb, cxx-objdump | cpsa | crmsh, pcmk | croc | cryptol, cry | csharp, c# | csound, csound-orc | csound-document, csound-csd | csound-score, csound-sco | css+django, css+jinja | css+erb, css+ruby | css+genshitext, css+genshi | css+lasso | css+mako | css+mako | css+mozpreproc | css+myghty | css+php | css+smarty | css | cucumber, gherkin | cuda, cu | cypher | cython, pyx, pyrex | d-objdump | d | dart | delphi, pas, pascal, objectpascal | dg | diff, udiff | django, jinja | docker, dockerfile | doscon | dpatch | dtd | duel, jbst, jsonml+bst | dylan-console, dylan-repl | dylan-lid, lid | dylan | earl-grey, earlgrey, eg | easytrieve | ebnf | ec | ecl | eiffel | elixir, ex, exs | elm | emacs, elisp, emacs-lisp | erb | erl | erlang | evoque | extempore | ezhil | factor | fan | fancy, fy | felix, flx | fish, fishshell | flatline | fortran | fortranfixed | foxpro, vfp, clipper, xbase | fsharp | gap | gas, asm | genshi, kid, xml+genshi, xml+kid | genshitext | glsl | gnuplot | go | golo | gooddata-cl | gosu | groff, nroff, man | groovy | gst | haml | handlebars | haskell, hs | haxeml, hxml | hexdump | hsail, hsa | html+cheetah, html+spitfire, htmlcheetah | html+django, html+jinja, htmldjango | html+evoque | html+genshi, html+kid | html+handlebars | html+lasso | html+mako | html+mako | html+myghty | html+php | html+smarty | html+twig | html+velocity | html | http | hx, haxe, hxsl | hybris, hy | hylang | i6t | idl | idris, idr | iex | igor, igorpro | inform6, i6 | inform7, i7 | ini, cfg, dosini | io | ioke, ik | irc | isabelle | j | jade | jags | jasmin, jasminxt | java | javascript+mozpreproc | jcl | jlcon | js+cheetah, javascript+cheetah, js+spitfire, javascript+spitfire | js+django, javascript+django, js+jinja, javascript+jinja | js+erb, javascript+erb, js+ruby, javascript+ruby | js+genshitext, js+genshi, javascript+genshitext, javascript+genshi | js+lasso, javascript+lasso | js+mako, javascript+mako | js+mako, javascript+mako | js+myghty, javascript+myghty | js+php, javascript+php | js+smarty, javascript+smarty | js, javascript | jsgf | json | jsonld, json-ld | jsp | julia, jl | kal | kconfig, menuconfig, linux-config, kernel-config | koka | kotlin | lagda, literate-agda | lasso, lassoscript | lcry, literate-cryptol, lcryptol | lean | less | lhs, literate-haskell, lhaskell | lidr, literate-idris, lidris | lighty, lighttpd | limbo | liquid | live-script, livescript | llvm | logos | logtalk | lsl | lua | make, makefile, mf, bsdmake | mako | mako | maql | mask | mason | mathematica, mma, nb | matlab | matlabsession | minid | modelica | modula2, m2 | monkey | moocode, moo | moon, moonscript | mozhashpreproc | mozpercentpreproc | mql, mq4, mq5, mql4, mql5 | mscgen, msc | mupad | mxml | myghty | mysql | nasm | ncl | nemerle | nesc | newlisp | newspeak | nginx | nimrod, nim | nit | nixos, nix | nsis, nsi, nsh | numpy | objdump-nasm | objdump | objective-c++, objectivec++, obj-c++, objc++ | objective-c, objectivec, obj-c, objc | objective-j, objectivej, obj-j, objj | ocaml | octave | odin | ooc | opa | openedge, abl, progress | pacmanconf | pan | parasail | pawn | perl, pl | perl6, pl6 | php, php3, php4, php5 | pig | pike | pkgconfig | plpgsql | postgresql, postgres | postscript, postscr | pot, po | pov | powershell, posh, ps1, psm1 | praat | prolog | properties, jproperties | protobuf, proto | ps1con | psql, postgresql-console, postgres-console | puppet | py3tb | pycon | pypylog, pypy | pytb | python, py, sage | python3, py3 | qbasic, basic | qml, qbs | qvto, qvt | racket, rkt | ragel-c | ragel-cpp | ragel-d | ragel-em | ragel-java | ragel-objc | ragel-ruby, ragel-rb | ragel | raw | rb, ruby, duby | rbcon, irb | rconsole, rout | rd | rebol | red, red/system | redcode | registry | resource, resourcebundle | rexx, arexx | rhtml, html+erb, html+ruby | roboconf-graph | roboconf-instances | robotframework | rql | rsl | rst, rest, restructuredtext | rts, trafficscript | rust | sass | sc, supercollider | scala | scaml | scheme, scm | scilab | scss | shen | silver | slim | smali | smalltalk, squeak, st | smarty | sml | snobol | sourceslist, sources.list, debsources | sp | sparql | spec | splus, s, r | sql | sqlite3 | squidconf, squid.conf, squid | ssp | stan | swift | swig | systemverilog, sv | tads3 | tap | tcl | tcsh, csh | tcshcon | tea | termcap | terminfo | terraform, tf | tex, latex | text | thrift | todotxt | trac-wiki, moin | treetop | ts, typescript | turtle | twig | typoscript | typoscriptcssdata | typoscripthtmldata | urbiscript | vala, vapi | vb.net, vbnet | vcl | vclsnippets, vclsnippet | vctreestatus | velocity | verilog, v | vgl | vhdl | vim | wdiff | x10, xten | xml+cheetah, xml+spitfire | xml+django, xml+jinja | xml+erb, xml+ruby | xml+evoque | xml+lasso | xml+mako | xml+mako | xml+myghty | xml+php | xml+smarty | xml+velocity | xml | xquery, xqy, xq, xql, xqm | xslt | xtend | xul+mozpreproc | yaml+jinja, salt, sls | yaml | zephir |

Tip: Try the Pygments Demo at http://pygments.org/

Literalinclude

There also is a literalinclude directive.

Placeholders

Placeholders in this context are named tags in code and example URLs where the exact value does not matter, but is referenced in the surrounding documentation. Use the Backus-Naur form <placeholder-name> for placeholders in code and URLs, i.e. use angle brackets to encapsulate the placeholder name.

For example in PHP

Set up a controller class to handle user interaction with the entity data
model:

.. code-block:: php

   class <Entity>Controller extends ActionController
   {
      ..
   }

where `<Entity>` corresponds to the entity data model class name.

or on the command line

Importing a TYPO3 dump file is as simple as running:

.. code-block:: bash

   typo3/sysext/core/bin/typo3 impexp:import <file>

where `<file>` can be the absolute path on the server or the relative path
in the TYPO3 project folder.

or in an example URL

The TYPO3 backend normally appends the session token ID to the URL as
follows: :samp:`https://example.org/typo3/main?token=<token-id>`.

In the XML and HTML markup languages, which make extensive use of angle brackets, the comment tag <!-- placeholder-name --> is used to insert placeholders. A <placeholder-name> looks like a regular element and would lead to confusion.