Extension:Highlightjs Integration

MediaWiki extensions manual

Highlightjs Integration Release status: stable
Implementation	Tag
Description	Allows to use the client-side syntax highlighter highlight.js in MediaWiki
Author(s)	Nikus Pokus
Latest version	1.2
MediaWiki
Database changes	No
License	GNU Affero General Public License 3.0
Download	GitHub: project page git repository URL [help ] commit history Note: No localisation updates are provided by translatewiki.net . README
Tags <syntaxhighlight> <source>
Hooks used BeforePageDisplay ParserFirstCallInit
Check usage and version matrix.

The Highlightjs Integration extension is a drop-in replacement for the SyntaxHighlight extension. Instead of using Pygments as server-side highlighter, it uses highlight.js a client-side JavaScript highlighter. It makes the wikis which use a lot of syntax highlighting faster.

Installation

• Download and place the file(s) in a directory called Highlightjs_Integration in your extensions/ folder.
• Add the following code at the bottom of your LocalSettings.php:

  wfLoadExtension( 'Highlightjs_Integration' );
  

•  Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension(). If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'Highlightjs_Integration' );, you need to use:

require_once "$IP/extensions/Highlightjs_Integration/Highlightjs_Integration.php";

Usage

Once installed, you can use the "syntaxhighlight" or the "source" tags on wiki pages. For example,

<syntaxhighlight>
<?php
// some php code
</syntaxhighlight>

Parameters

lang

If no "lang" attribute is defined, the highlight.js library tries itself to determine the language.
The lang="name" attribute defines what lexer should be used. This affects how the extension highlights the source code.

<syntaxhighlight lang="php">
<?php
// some php code
</syntaxhighlight>

The highlight.js library supports 176 languages. Specifying an invalid or unknown name will make the highlight.js library unable to highlight the source code.

inline

The attribute indicates that the source code should be inline as part of a paragraph (as opposed to being its own block). For example:

An extract of source <syntaxhighlight lang="php" inline><?php echo "Done!"; ?></syntaxhighlight> on one line.

Configuration

Style

The highlight.js library supports 79 styles.
To change the style edit the file "extensions/Highlightjs_Integration/extension.json" and modify the line "highlight/styles/railscasts.css"

    ...
    "ResourceModules": {
        "ext.HighlightjsIntegration": {
            ...
            "styles": [
                "custom.css",
                "highlight/styles/railscasts.css"
            ],
            ...
        }
    },
    ...

Tags

By default you can use the "syntaxhighlight" or the "source" tags to highlight source code.
To add other tags or remove some, edit the file "extensions/Highlightjs_Integration/extension.json" and modify the following block:

    ...
    "config": {
        "HighlightTags": [
            "syntaxhighlight",
            "source"
        ],
        ...
    },
    ...

Mapping between languages

If you used SyntaxHighlight, you will find some languages have different names in the highlight.js library and some have missing.
To map a language name to an existing language in the highlight.js library, edit the file "extensions/Highlightjs_Integration/extension.json" and modify the following block:

    ...
    "config": {
        ...
        "LangMapping": {
            "tsql": "sql",
            "mysql": "sql",
            "vb": "vbscript",
            "vba": "vbscript",
            "xaml": "xml",
            "mediawiki": "markdown"
        }
    },
    ...

highlight.js

This extension is bundled with highlight.js version 9.12 and the following languages:
Common languages (23):

• Apache
• Bash
• C#
• C++
• CSS
• CoffeeScript
• Diff
• HTML, XML
• HTTP
• Ini
• JSON
• Java
• JavaScript
• Makefile
• Markdown
• Nginx
• Objective-C
• PHP
• Perl
• Python
• Ruby
• SQL
• Shell Session

HighlightJS 10

If you want a different version of the highlight.js library or to add or remove languages:

1. go on the download page of the highlight.js website and download a custom package.
2. remove or rename the extensions/Highlightjs_Integration/highlight folder.
3. unarchive the custom package in extensions/Highlightjs_Integration. You should have a fresh new extensions/Highlightjs_Integration/highlight folder.

To upgrade from HighlightJS 9 to HighlightJS 10, modify extension.json with the following:

• change "highlight.pack.js" to "highlight.min.js", and
• change "railscasts.css" to "railscasts.min.css".

Note that you will need the built CDN Release version of HighlightJS unless you plan on building it yourself.

See also

• highlight.js javascript syntax highlighter
• Related extensions:
  • HighlightJS – another MediaWiki extension for highlight.js.
  • SyntaxHighlight – server-side syntax highlighter that uses Pygments.