--- layout: wiki title: WikiProcessors updated: 2021-04-16 08:14 author: trac default: true --- ## Wiki Processors Processors are [WikiMacros](/briareus/notes/WikiMacros/) that provide alternative markup formats for the [Wiki engine](/briareus/notes/TracWiki/). Processors can be thought of as *macro functions to process user-edited text*. Wiki processors can be used in any Wiki text throughout Trac, such as: - syntax highlighting or for rendering text verbatim - rendering Wiki markup inside a context such as
or blocks or within or table cells - using an alternative markup syntax, like [raw HTML](/briareus/notes/WikiHtml/) and [Restructured Text](/briareus/notes/WikiRestructuredText/) or [textile](https://www.booked.net/textism.html) ### Using Processors To use a processor on a block of text, first delimit the lines using a Wiki *code block*: ``` {{{ The lines that should be processed... }}} ``` Immediately after the \`{{{\` or on the line just below, add \`#\!\` followed by the *processor name*: ``` {{{ #!processorname The lines that should be processed... }}} ``` This is the "shebang" notation, familiar to most UNIX users. Besides their content, some Wiki processors can also accept *parameters*, which are then given as \`key=value\` pairs after the processor name and on the same line. If \`value\` has to contain space, as it's often the case for the style parameter, a quoted string can be used (\`key="value with space"\`). As some processors are meant to process Wiki markup, it's quite possible to *nest* processor blocks. You may want to indent the content of nested blocks for increased clarity, this extra indentation will be ignored when processing the content. ### Examples | Wiki Markup | Display | |---|---| ```td '''Example 1''': Inserting raw HTML ``` \|----------------------------------------------------------------- ```td {{{ {{{ #!html

This is raw HTML

}}} }}} ``` ```td {{{ #!html

This is raw HTML

}}} ``` \|----------------------------------------------------------------- ```td '''Example 2''': Highlighted Python code in a
block with custom style ``` \|----------------------------------------------------------------- ```td {{{ {{{#!div style="background: #ffd; border: 3px ridge" This is an example of embedded "code" block: {{{ #!python def hello(): return "world" }}} }}} }}} ``` ```td {{{#!div style="background: #ffd; border: 3px ridge" This is an example of embedded "code" block: {{{ #!python def hello(): return "world" }}} }}} ``` \|----------------------------------------------------------------- ```td '''Example 3''': Searching tickets from a wiki page, by keywords. ``` \|----------------------------------------------------------------- ```td {{{ {{{ #!html
}}} }}} ``` ```td {{{ #!html
}}} ``` ### Available Processors The following processors are included in the Trac distribution:
**\`#\!default\`**Present the text verbatim in a preformatted text block. This is the same as specifying *no* processor name (and no \`#\!\`).
**\`#\!comment\`**Do not process the text in this section, i.e. contents exist only in the plain text - not in the rendered page.
**\`#\!rtl\`**Introduce a Right-To-Left block with appropriate CSS direction and styling. *(since 0.12.2)*
**HTML related**
**\`#\!html\`**Insert custom HTML in a wiki page.
**\`#\!htmlcomment\`**Insert an HTML comment in a wiki page. (*since 0.12*)
Note that \`#\!html\` blocks have to be *self-contained*, i.e. you can't start an HTML element in one block and close it later in a second block. Use the following processors for achieving a similar effect.
**\`#\!div\`**Wrap wiki content inside a
element.
**\`#\!span\`**Wrap wiki content inside a element.
**\`#\!td\`**Wrap wiki content inside a element. (*since 0.12*)
**\`#\!th\`**Wrap wiki content inside a element. (*since 0.12*)
**\`#\!tr\`**Can optionally be used for wrapping \`#\!td\` and \`#\!th\` blocks, either for specifying row attributes or better visual grouping. (*since 0.12*)
**\`#\!table\`**Can optionally be used for wrapping \`#\!tr\`, \`#\!td\` and \`#\!th\` blocks, for specifying table attributes. One current limitation however is that tables cannot be nested. (*since 0.12*)
See [WikiHtml](/briareus/notes/WikiHtml/) for example usage and more details about these processors.
**Other Markups**
**\`#\!rst\`**Trac support for Restructured Text. See [WikiRestructuredText](/briareus/notes/WikiRestructuredText/).
**\`#\!textile\`**Supported if [Textile](https://pypi.org/project/textile) is installed. See [a Textile reference](https://www.booked.net/textism.html).
**Code Highlighting Support**
**\`#\!c\`**
**\`#\!cpp\`** (C++)
**\`#\!python\`**
**\`#\!perl\`**
**\`#\!ruby\`**
**\`#\!php\`**
**\`#\!asp\`**
**\`#\!java\`**
**\`#\!js\`** (Javascript)
**\`#\!sql\`**
**\`#\!xml\`** (XML or HTML)
**\`#\!sh\`** (\!Bourne/Bash shell)
Trac includes processors to provide inline syntax highlighting for source code in various languages.

Trac relies on [Pygments](http://pygments.org) for syntax coloring.

See [TracSyntaxColoring](/briareus/notes/TracSyntaxColoring/) for information about which languages are supported and how to enable support for more languages.
Since 1.1.2 the default, coding highlighting and MIME-type processors support the argument \`lineno\` for adding line numbering to the code block. When a value is specified, as in \`lineno=3\`, the numbering will start at the specified value. When used in combination with the \`lineno\` argument, the \`marks\` argument is also supported for highlighting lines. A single line number, set of line numbers and range of line numbers are allowed. For example, \`marks=3\`, \`marks=3-6\`, \`marks=3,5,7\` and \`marks=3-5,7\` are all allowed. The specified values are relative to the numbered lines, so if \`lineno=2\` is specified to start the line numbering at 2, \`marks=2\` will result in the first line being highlighted. Using the MIME type as processor, it is possible to syntax-highlight the same languages that are supported when browsing source code. | **MIME Type Processors** | |---| ```tr {{{#!td Some examples: {{{ {{{#!text/html

text

}}} }}} }}} {{{#!td The result will be syntax highlighted HTML code: {{{#!text/html

text

}}} The same is valid for all other [TracSyntaxColoring#SyntaxColoringSupport mime types supported]. }}} ``` ```td {{{ {{{#!diff --- Version 55 +++ Version 56 @@ -115,8 +115,9 @@ name='TracHelloWorld', version='1.0', packages=find_packages(exclude=['*.tests*']), - entry_points = """ - [trac.plugins] - helloworld = myplugs.helloworld - """, + entry_points = { + 'trac.plugins': [ + 'helloworld = myplugs.helloworld', + ], + }, ) }}} }}} ``` ```td '''`#!diff`''' has a particularly nice renderer: {{{#!diff --- Version 55 +++ Version 56 @@ -115,8 +115,9 @@ name='TracHelloWorld', version='1.0', packages=find_packages(exclude=['*.tests*']), - entry_points = """ - [trac.plugins] - helloworld = myplugs.helloworld - """, + entry_points = { + 'trac.plugins': [ + 'helloworld = myplugs.helloworld', + ], + }, ) }}} ``` Line numbers can be added to code blocks and lines can be highlighted //(since 1.1.2)//. ``` {{{#!python lineno=3 marks=3,9-10,16 def expand_markup(stream, ctxt=None): """A Genshi stream filter for expanding `genshi.Markup` events. Note: Expansion may not be possible if the fragment is badly formed, or partial. """ for event in stream: if isinstance(event[1], Markup): try: for subevent in HTML(event[1]): yield subevent except ParseError: yield event else: yield event }}} ``` ```python def expand_markup(stream, ctxt=None): """A Genshi stream filter for expanding `genshi.Markup` events. Note: Expansion may not be possible if the fragment is badly formed, or partial. """ for event in stream: if isinstance(event[1], Markup): try: for subevent in HTML(event[1]): yield subevent except ParseError: yield event else: yield event ``` For more processor macros developed and/or contributed by users, visit the [Trac Hacks](https://trac-hacks.org) community site. Processors are implemented using the same interfaces as Wiki macros, only the usage syntax differs. To develop a processor, see [WikiMacros](/briareus/notes/WikiMacros/)#DevelopingCustomMacros. --- See also: [WikiMacros](/briareus/notes/WikiMacros/), [WikiHtml](/briareus/notes/WikiHtml/), [WikiRestructuredText](/briareus/notes/WikiRestructuredText/), [TracSyntaxColoring](/briareus/notes/TracSyntaxColoring/), [WikiFormatting](/briareus/notes/WikiFormatting/), [TracGuide](/briareus/notes/TracGuide/)