Migration Guide

These instructions apply to v4 and up. If you are looking for instructions for older version, please see the original manual.

💰 💰 💰 Please click here to donate via PayPal and just like they say on TV – give generously! It motivates me to keep working on this (12 years now and counting).

Short Version

SyntaxHighlighter v4 is fully compatible with v3 brushes. You can bundle v3 brushes by passing them to the --brushes. Alternatively if you use --compat option to build syntaxhighlighter.js as described in the Building guide, you can simply drop v3 brushes on the page using <script/> tags, like in the good old days.

You no longer need to call SyntaxHighlighter.all(). It's executed automatically on DOMContentLoaded event.

Long Version

v3 vs v4

The brush format has barely changed from v3 to v4. Since we are using proper bundling in v4 instead of concatenation in v3, all brushes are now CommonJS compatible out of the box.

A typical v3 brush looks like this:

;(function()
{
  // CommonJS
  SyntaxHighlighter = SyntaxHighlighter || (typeof require !== 'undefined' ? require('shCore').SyntaxHighlighter : null);

  function Brush()
  {
    this.regexList = [...];
  };

  Brush.prototype = new SyntaxHighlighter.Highlighter();
  Brush.aliases = ['test_brush_v3'];

  SyntaxHighlighter.brushes.Compat = Brush;

  // CommonJS
  typeof(exports) != 'undefined' ? exports.Brush = Brush : null;
})();

Same brush in v4 format, with the least amount of changes possible:

var BrushBase = require('brush-base');

function Brush()
{
  this.regexList = [...];
};

Brush.prototype = new BrushBase();
Brush.aliases = ['test_brush_v4'];
module.exports = Brush;

What changed?

1. No longer relying on global SyntaxHighlighter variable.
2. shCore is no longer a thing.
3. Proper module.exports.

Bundling v3 Brushes

Bundling v3 brushes is enabled by adding the header to each v3 brush. This happens automatically if brush is determined to be v3.

IF SRC CONTAINS `require('shCore').SyntaxHighlighter`
  a. ADD CONTENT_OF build/templates/brush-v3-compatibility-header.js
  b. STOP

Loading v3 Brushes

Loading v3 brushes via <script/> tags is enabled by passing the --compat flag to the gulp build command. Compatibility mode exposes two global variables on the window object: SyntaxHighlighter and XRegExp (but not if window.XRegExp is already defined).