Reference

Description

The code macro displays source code with syntax highlighting: keywords, strings and comments are coloured according to the language of the code. In the macro list of the editors it appears as "Code", in the "Formatting" category.

The highlighting is computed on the server by Pygments, so readers receive the code already coloured. To highlight code in the browser instead, use the Prism.js extension.

Usage

{{code language="java"}}
System.out.println("Hello");
{{/code}}

Written on its own, the macro displays a block of code. Written inside a paragraph, it displays the code within the sentence, and the layout parameter has no effect.

The Pygments lexer documentation gives the short names to set language to, such as java, python or xml. It documents the latest Pygments, which can know languages that the one bundled with XWiki doesn't: the List the Languages Your Wiki Can Highlight example lists exactly those of your wiki. Without language, Pygments guesses the language from the code, which often fails on a short snippet. The value none displays the code without any highlighting. A language that Pygments doesn't know, or code that it fails to highlight, is displayed without highlighting rather than as an error. For another language, a developer can write a highlighter for it.

The highlighted result is reused when the page is displayed again, so highlighting large code costs time once. This doesn't apply to code read through source, which is highlighted at each display.

Parameters

The macro also accepts every parameter of the "box" Macro, such as title and cssClass.

Examples

A Block of Python Code

{{code language="python"}}
def greet(name):
    """Return a greeting for the given name."""
    return f"Hello, {name}!"

for user in ["Alice", "Bob"]:
    print(greet(user))
{{/code}}

Line Numbers

{{code language="python" layout="linenumbers"}}
def greet(name):
    ...
{{/code}}

Code Inside a Sentence

To list the files of the current directory, run {{code language="bash"}}ls -la{{/code}} in a terminal.

A Title Above the Code

{{code language="xml" title="pom.xml"}}
<dependency>
  <groupId>org.xwiki.platform</groupId>
  <artifactId>xwiki-platform-rendering-macro-code</artifactId>
</dependency>
{{/code}}

List the Languages Your Wiki Can Highlight

This table lists every language that the bundled Pygments knows, with the short names to give to language. It uses the Python Macro, bundled with XWiki, and needs programming right.

{{python}}
from pygments.lexers import get_all_lexers

print("|=Language|=Short Names|=File Patterns")
for name, aliases, patterns, mimetypes in sorted(get_all_lexers()):
    print("|%s|%s|%s" % (name, ", ".join(aliases), ", ".join(patterns)))
{{/python}}

Code Read From Somewhere Else

Instead of writing the code inside the macro, you can give its location with the source parameter, as <type>:<reference>. The content of the macro is then ignored.

When language is not set, the macro takes it from the source when it can: HTML, XML, JavaScript, JSON, PHP or CSS from the media type of an attachment, HTML from a page written in an HTML syntax, and Velocity from a text area property holding Velocity code. Otherwise, Pygments guesses it.

Reading the code from elsewhere has conditions:

• With script, the last author of the page must have script right, and the variable must exist; otherwise the macro displays an error. It also displays an error where scripts are not allowed to run, such as in a comment.
• With a page, an attachment or a property, both the last author of the page and the person viewing it must be allowed to view the page it comes from. The source must exist. A page given without a language is read in the language the reader is viewing, from its translation when it has one.
• An attachment larger than 1 MB is refused, unless an administrator raised the limit.

For example, with a fibonacci.js attachment on the page and no language given, the macro takes the language from the media type of the attachment:

{{code source="attachment:fibonacci.js"}}{{/code}}

Related

• "box" Macro
• Code Macro Configuration Properties
• Insert a Code Block with the BlockNote Editor
• Prism.js, to highlight code in the browser
• Replace the Code Macro with Prism.js
• Highlight Macro, to highlight code in the browser with Highlight.js
• Remote Code Macro, to highlight code read from a URL
• Caching Code Macro, to cache and render the highlighting asynchronously