Bob's Guides

SyntaxHighlighter Plugin Tutorial

If you use this extra and like it, please consider donating. The suggested donation for this extra is $10.00, but any amount you want to give is fine (really). For a one-time donation of $50.00 you can use all of my non-premium extras with a clear conscience.

SyntaxHighlighter provides front-end syntax highlighting for MODX Revolution. SyntaxHighlighter is a Revolution version of Alex Gorbatchev's JavaScript Syntax Highlighter. The plugin and snippet code itself and the installer are mine, but the rest of the code is Alex's. Theme property and updates thanks to AlexZem

The SyntaxHighlighter package installs both a plugin and a snippet. Either one will highlight just about any kind of code and will provide options for line numbers in the "gutter" on the left side of the code and highlighting for specific lines. There are also a variety of SyntaxHighlighter themes, and you can create your own. The line numbers can be turned off if you don't want them. You can use either the plugin or the snippet, but not both. For maximum speed, use neither one (see the section below on Speed Considerations).

[Syntax Highlighter is fully compatible with MODX 3 and PHP 8]

The Plugin

The SyntaxHighlighter plugin is enabled by default. To disable it, edit the plugin, check the "disabled" checkbox, and save the plugin. If you use the snippet you must disable the plugin.

The plugin will fire on every page at your site. It is relatively fast, but it will slow the site down slightly as it parses every page looking for code to highlight, though most of this is done in JavaScript that will be cached by your browser. If you have a code-intensive site, this is fine, but if you only have code on a few pages, the snippet may be a better option. If you use the snippet, be sure to disable the plugin! The plugin will only affect code in <pre> tags with a particular class (see the Usage section below).

The various kinds of highlighting — one for each type of code (HTML, PHP, CSS, etc.) — are called "brushes". The &brushes property of the snippet will determine which brushes are loaded. For the plugin, you must specify every brush used on the site in the &brushes property.

The System Setting

The syntaxhighlighter.theme System Setting sets the default theme to be used by SyntaxHighlighter. The theme will be used by default throughout the site. The available themes are: Default, Django, Eclipse, Emacs, FadeToGrey, MDUltra, Midnight, and RDark. They are case-sensitive.

The Snippet

The snippet is particularly useful if you only have code on a few pages, or if you want a different SH theme for some pages. You can specify the brushes to load in the snippet tag so that only the brushes used on the page are loaded. If no brushes are specified in the tag, the default brushes (JScript,Xml,Php,Css,Plain) are loaded. To highlight code on a page, place a SyntaxHighlighter snippet tag at the top of the page content (or in the template):

[[SyntaxHighlighter? &brushes=`Css,Php` &theme=`Midnight`]]

Both properties are optional. If omitted, the default brushes listed above will be loaded and the theme will come from the syntaxhighlighter.theme System Setting.

Usage

SyntaxHighlighter (SH) will only affect code wrapped in <pre> tags. In order to let SH know what type of code it is, you need to specify a "brush" in the opening <pre> tag like this:

<pre class="brush: php">

The line above tells SH that you want the php brush. By default, brushes are loaded for php, css, xml, jscript, and plain. The plain brush styles the selection as preformatted, but does no highlighting. It's useful for MODX tags (though there really should be a brush for that too).

There may be angle bracket within your code, for example, if ($x < $y), it's important that any left angle-brackets in the code be converted to HTML entities (<) before SH sees the code, otherwise, SH may get confused. If you are displaying MODX tags, the first left bracket ([) must also be converted to [ You can convert them manually, or you can use the FixedPre plugin to do it for you. FixedPre fires during OnParseDocument, so it will convert the code and remove the <fixedpre> tags before SyntaxHighlighter sees it. If you use FixedPre, do not convert the tags to HTML entities or the raw entities will be displayed.

If you already have FixedPre installed, be sure to update it to at least version 1.0.2-pl. Earlier versions are not compatible with SyntaxHighlighter. Note that the later versions of FixedPre no longer insert <span> tags. If you use those for styling, see the FixedPre tutorial here.

Important: If you use SyntaxHighlighter with FixedPre, make sure the FixedPre tags are inside the SyntaxHighlighter tags. Otherwise, FixedPre will "entify" the <pre> tags and SyntaxHighlighter won't see them.

Other Brushes

SH has many brushes including ones for SQL, AppleScript, ColdFusion, Delphi, Ruby, Python, Perl, VB, Java, and many more. To see the available brushes, look in the assets/components/syntaxhighlighter/scripts/ directory. In order to use other brushes, you need to specify them, separated by commas, in the &brushes property of SH. In the snippet, you can do this in the &brushes property (separate them with commas).

The brush names are mixed case and must be specified correctly in the &brushes property of the snippet or plugin. They are the filenames from the scripts directory minus the leading "shBrush" and the extension. For example, the file shBrushJScript.js is specified in the &brushes property as 'JScript'.

When you specify the brush in the <pre> tag, however, you must use the lower-case alias for the brush. In the case of the JScript brush, the alias is js. The default brush aliases are php, css, xml, js, and plain. Note that xml is used to highlight both XML and HTML. For other brushes, you can look near the end of the brush.js file that's being included to see the aliases, though usually a lowercase version of the code type will work (e.g., python, ruby, sql, perl, java, vb, bash, csharp, etc.).

If you specify a brush in the <pre> tag that is not loaded in the &brush property, a JavaScript alert will pop up and tell you the name of the missing brush. This usually means you have used the wrong alias for that brush.

Important: The brushes to be loaded by the &brushes property are case-sensitive and must match the brush-name part of the file name. When you specify a brush in a <pre> tag, however, the brush name must be all lowercase.

Options

Various options can be specified in the <pre> tag by adding them after the class specification. Here's what the most common ones look like in a tag:

<pre class="brush: php; toolbar: false; gutter: true; highlight: [2,3];">
   /* Code here */
</pre>

The option settings shown above will turn off the toolbar (the icon on the right side of preformatted sections) and the line numbers off, and will highlight lines two and three of the code. Notice the semicolon at the end of each option specification.

That will look like this:

    <?php
    function modify($x, $y) {
       $x = $x * 3;
       $y = $y + 2;
       return $x + $y;
    }
    

Note that, as I said above, the links in the toolbar do not work. They could be adjusted to go to the GitHub site, but frankly, there's not much help to be found there, and they are hardcoded into every brush and theme file. I always turn the toolbar off.

CSS

Both the plugin and the snippet will automatically load the CSS for the brushes you have selected in the brushes property of the plugin or the snippet. Either one will use the syntaxhighlighter.theme System Setting to select load the theme CSS file. Both will inject the code at the end of the <head> section of your template. If you want the same SyntaxHighlighter options throughout your site, this is ideal. You can select the language with brush: followed by the lowercase language name (e.g., php, html, css) in the <pre> tag and specify the option in that tag as well.

If you use the plugin, and you don't use the default brushes, you should create a property set for the plugin so your selections won't be overwritten by upgrades the SyntaxHighlighter. For the snippet, specify any non-default options in the snippet tag.

When using the snippet, you can override the theme with the &theme property in the snippet tag. The tag can go in the page content or the template. You can only have one theme per page. If you call the snippet multiple times with different &theme property values, the value in the last snippet tag on the page will be used for all <pre> sections on the page.

If you're using the plugin, you can still override the theme for a particular template, but it's tricky and I don't recommend it. That said, I do it at Bob's Guides, which has a different theme for the blog pages.

The problem is that the plugin (like the snippet) injects the theme CSS at the end of the <head> section of your template, which makes it difficult to override it with your own custom CSS for the <pre> sections.

The trick is to load the same theme selected in the syntaxhighlighter.theme System Setting manually at the top of the <head> section of your template. This prevents the snippet and plugin from injecting the CSS because it has already been loaded. You can then place your own CSS link below those lines. It will override the CSS in the selected theme. It's an ugly hack, but it works.

That looks like this in the template:

<link rel="stylesheet"
      href="[[++assets_url]]components/syntaxhighlighter/css/shCore.css" type="text/css" />

    <link rel="stylesheet"
          href="[[++assets_url]]components/syntaxhighlighter/css/shThemeDefault.css"
          type="text/css" />

    <link rel="stylesheet"
          href="css/blogresponsive.css" type="text/css"/>

You'll need to adjust the last one above to match the path to your own CSS file.

Different brushes for individual <pre> sections.

Although you can only have one SyntaxHighlighter theme per page, you can vary the language highlighting scheme for each <pre> section by using the lowercase language name (assuming that you have loaded that brush) in the brush part of the <pre> tag as shown above.

Speed Considerations

There are a number of ways to speed up the operation of SyntaxHighlighter. The easiest is to just eliminate any brushes you don't use on the site from the brushes property of the plugin or specify just the brushes you need in the snippet tag.

Another trick is to enable SH using either the snippet or plugin and view the source code of a page. Copy the relevant SH lines directly into your template(s) or page content at the appropriate places, then disable the SyntaxHighlighter plugin or remove the snippet tag. Don't forget the script at the bottom of the page. It can be moved below the final <html> tag so that the browser will finish rendering the HTML before executing the function, but visitors on slow connections may see the unformatted code before the formatted code appears.

Further speed increases can be gained by appending the content of the two CSS files into your site's CSS file and removing the SyntaxHighlighter CSS file references in the template.

Finally, for even more speed, you can copy the contents of the brush files you actually use into a single .js file and just refer to that file with a single line in the template. You could also place all the js code in the template itself, but since your browser will cache the js code, this is would probably make page loads slower rather than faster.

Copyright © 2011-2025
Bob Ray