org.xwiki.platform:xwiki-platform-rendering-macro-codeXWiki Platform - Rendering - Macro - Codejar00.0XWiki Platform - Rendering - Macro - CodeSee https://pygments.org/languages/ for the list of all supported languages. If you have a hard time finding the right id for the language, you can look at https://pygments.org/docs/lexers/ (##Short names##).
{{info}}
There are also some other syntax highlighting macros that work client-side:
* [[Prism.js Macro>>Extension.PrismMacro.WebHome]].
* [[Highlight Macro>>Extension.Highlight Macro]].
{{/info}}
== Usage ==
The macro can work both in inline mode or standalone mode.
Standalone mode:
{{code language="none"}}
{{code language=<providedlanguage>}}
... code here...
{{/code}}
{{/code}}
Inline mode:
{{code language="none"}}
Some content {{code language=<providedlanguage>}}... code here...{{/code}} other possible content here
{{/code}}
{{version since="17.2.0, 16.10.6"}}
The result of the highlighting is cached, so this expensive step should only be required once for a cached page.
{{/version}}
=== Example ===
Example result:
{{image reference="example.png"/}}
=== Parameters definition ===
This macro also supports all [[Box Macro parameters>>Box Macro||anchor="HParametersdefinition"]].
|=Name|=Optional|=Allowed values|=Default value|=Description
|language|yes|a string|the macro tries to determine the syntax|the 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.
|layout|yes|(((
* ##plain##: the result of the parser
* ##linenumbers##: add line numbers
)))|##plain##|{{version since="11.5"}}The layout to apply to the code.{{/version}}
|source|yes|[[source reference>>||anchor="HSource"]]||{{version since="14.10.2"}}The reference of a content to highlight instead of the macro content.{{/version}}
==== Source ====
{{version since="14.10.2"}} {{/version}}
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 ({{box}}~{{code source="string:content to highlight"/}}{{/box}}), it's also the default type when none is provided ({{box}}~{{code source="content to highlight"/}}{{/box}})
* ##script##: the reference is the name of a script binding in the current script context, using it requires SCRIPT right.(((
{{box}}
{{{
{{velocity}}
#set($myvar = "some content to highlight")
{{/velocity}}
{{code source="script:myvar"/}}
}}}
{{/box}}
)))
* ##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 {{box}}~{{code source="document:Space.Document"/}}{{/box}}
** ##attachment##: highlight the content of the attachment, uses document attachment reference format as in {{box}}~{{code source="attachment:Space.Document@file.txt"/}}{{/box}}. 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 {{box}}~{{code source="object_property:Space.Document^ClassSpace.ClassName.property"/}}{{/box}}
** ##page##: highlight the content of the page, uses page reference format as in {{box}}~{{code source="page:Page/SubPage"/}}{{/box}}
** ##page_attachment##: highlight the content of the attachment, uses page attachment reference format as in {{box}}~{{code source="page_attachment:Page/SubPage/file.txt"/}}{{/box}}. 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.
{{code language="java"}}
@Component
@Singleton
@Named("mytype")
public class MyCodeMacroSourceFactory implements CodeMacroSourceFactory
{
@Override
public CodeMacroSource getContent(CodeMacroSourceReference reference, MacroTransformationContext context)
throws MacroExecutionException
{
return new CodeMacroSource(reference, getContent(reference.getReference()), getLanguage(reference.getReference()));
}
}
{{/code}}
{{box}}
~{{code source="mytype:myreference"/}}
{{/box}}
=== Configuration ===
It's possible to set some configuration for this macro in the ##xwiki.properties## file:
|=Name|=Optional|=Allowed values|=Default value|=Description
|rendering.macro.code.pygments.style|yes|a string|##default##|{{version since="2.4"}}the name of the Pygments style to use. See http://pygments.org/docs/styles/ for more about styles.{{/version}} {{version since="16.10.0"}}The ##default## style in the context of the code macro has been updated for better contrast.{{/version}}
|rendering.macro.code.source.attachmentMaximumSize|yes|a size in bytes|1000000|{{version since="14.10.2"}}Indicate the maximum allowed size for an attachment used as code macro source{{/version}}
== Adding new languages ==
Anyone can add a new language support by:
* adding a XWiki java component: implementing {{scm path="xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-code/src/main/java/org/xwiki/rendering/parser/HighlightParser.java"}}HighlightParser interface{{/scm}} component. See [[Component Module>>Component Module]] for more details on how to write component for the new XWiki 2.0 architecture
* the default ##org.xwiki.rendering.parser.HighlightParser## is based on [[Pygments>>http://pygments.org]] so the best for both projects is probably to provide a new syntax parser to [[Pygments>>http://pygments.org]] project. See [[http://pygments.org/contribute/]].
== Example ==
{{code language="none"}}
{{code language="html"}}
<html>
<head>Cool!</head>
</html>
{{/code}}
{{/code}}
=== Result ===
{{code language="html"}}
<html>
<head>Cool!</head>
</html>
{{/code}}
== Listing all supported languages ==
The list is on the [[Pygments language list>>https://pygments.org/languages/]]. 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):
{{code language="python"}}
{{python}}
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])
{{/python}}
{{/code}}
GNU Lesser General Public License 2.1http://extensions.xwiki.org/xwiki/bin/view/Extension/Code%20Macro/XWiki Development Teamhttps://xwiki.org/xwiki/bin/view/XWiki/XWikiTeamgitgit://github.com/xwiki/xwiki-platform.git/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-codegitgit@github.com:xwiki/xwiki-platform.git/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-codehttps://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwiki-platform-rendering/xwiki-platform-rendering-macros/xwiki-platform-rendering-macro-code/jirahttps://jira.xwiki.org/browse/XWIKIfalsemaven.groupidorg.xwiki.platformmaven.artifactidxwiki-platform-rendering-macro-codemaven.Modelorg.xwiki.platform:xwiki-platform-rendering-macro-code:jar:18.7.0xwiki.extension.recommendedVersions.commonsorg.xwiki.commons:.*/[18.7.0]xwiki.extension.recommendedVersions.platformorg.xwiki.commons:.*/[18.7.0],
org.xwiki.rendering:.*/[18.7.0],
org.xwiki.platform:.*/[18.7.0]xwiki.extension.recommendedVersionsorg.xwiki.commons:.*/[18.7.0],
org.xwiki.rendering:.*/[18.7.0],
org.xwiki.platform:.*/[18.7.0]4.4maven-xwikihttps://nexus.xwiki.org/nexus/content/groups/publicmaven