Code Macro

Version 10191.1 by Admin on 2024/06/01 17:17

cogHighlights code
Developed by

XWiki Development Team

0 Votes
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard

Installable with the Extension Manager


See for the list of all supported languages. If you have a hard time finding the right id for the language, you can look at (Short names).

See also the Highlight Macro.


The macro can work both in inline mode or standalone mode.

Standalone mode:

{{code language=<providedlanguage>}}
... code here...

Inline mode:

Some content {{code language=<providedlanguage>}}... code here...{{/code}} other possible content here


Example result:


Parameters definition

This macro also supports all Box Macro parameters.

NameOptionalAllowed valuesDefault valueDescription
languageyesa stringthe macro tries to determine the syntaxthe language identifier of the provided code snippet. If no language identifier is specified then the macro will try to determine the syntax. To avoid highlight, you can use "none" language identifier.
  • plain: the result of the parser
  • linenumbers: add line numbers
plainXWiki 11.5+ The layout to apply to the code.
sourceyessource referenceXWiki 14.10.2+ The reference of a content to highlight instead of the macro content.


XWiki 14.10.2+  

The format of the reference of the source is <source type>:<reference>.

The code macro currently supports the following types of sources:

  • string: the reference is the content to highlight ({{code source="string:content to highlight"/}}), it's also the default type when none is provided ({{code source="content to highlight"/}}
  • script: the reference is the name of a script binding in the current script context, using it requires SCRIPT right.
    #set($myvar = "some content to highlight")
    {{code source="script:myvar"/}}
  • entity: the reference is the typed entity reference if the content to highlight, the supported entities are
    • document: highlight the content of the document, uses document reference format as in {{code source="document:Space.Document"/}}
    • attachment: highlight the content of the attachment, uses document attachment reference format as in {{code source="attachment:[email protected]"/}}. By default, it's not allowed to use an attachment bigger than 1MB as source.
    • object_property: highlight the content of the object property, uses document object property reference format as in {{code source="object_property:Space.Document^"/}}
    • page: highlight the content of the page, uses page reference format as in {{code source="page:Page/SubPage"/}}
    • page_attachment: highlight the content of the attachment, uses page attachment reference format as in {{code source="page_attachment:Page/SubPage/file.txt"/}}. By default, it's not allowed to use an attachment bigger than 1MB as source.
Add support for a new source type

To add support for a new type of source, you need to provide a component implementing role org.xwiki.rendering.macro.code.source.CodeMacroSourceFactory and having as role hint the prefix to use in the source reference.

public class MyCodeMacroSourceFactory implements CodeMacroSourceFactory
   public CodeMacroSource getContent(CodeMacroSourceReference reference, MacroTransformationContext context)
       throws MacroExecutionException
       return new CodeMacroSource(reference, getContent(reference.getReference()), getLanguage(reference.getReference()));

{{code source="mytype:myreference"/}}


It's possible to set some configuration for this macro in the file:

NameOptionalAllowed valuesDefault valueDescription
rendering.macro.code.pygments.styleyesa stringdefaultXWiki 2.4+ the name of the Pygments style to use. See for more about styles.
rendering.macro.code.source.attachmentMaximumSizeyesa size in bytes1000000XWiki 14.10.2+ Indicate the maximum allowed size for an attachment used as code macro source

Adding new languages

Anyone can add a new language support by:


{{code language="html"}}



Listing all supported languages

The list is on the Pygments language list. However if you want to dynamically check the list of supported language for the XWiki version used of Pygments, you could put the following in a wiki page, using a user with Programming Rights (and assuming that the Python Macro is installed):

import pygments
from pygments.lexers import get_all_lexers

print "|=Language |=Name |=File Extension |=Mime Types"
for lexer in sorted(get_all_lexers()):
   print "| ", lexer[0], " | ", ", ".join(lexer[1]), " | ", ", ".join(lexer[2]), " | ", ", ".join(lexer[3])


Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.


Dependencies for this extension (org.xwiki.platform:xwiki-platform-rendering-macro-code 16.4.0):

Get Connected