Jump to content

Extension:Highlightjs Integration

From mediawiki.org
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 2.2
MediaWiki
Database changes No
License GNU Affero General Public License 3.0
Download
README
<syntaxhighlight> <source>

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

[edit]
  • 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 file:
    wfLoadExtension( 'Highlightjs_Integration' );
    
  • Yes Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

Usage

[edit]

Once installed, you can use the syntaxhighlight or the source tags on wiki pages:

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

Parameters

[edit]

lang

[edit]

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 this extension highlights the source code.

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

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

inline

[edit]

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

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

Configuration

[edit]

Style

[edit]

The highlight.js library supports color themes.
To change the theme, edit the file "extensions/Highlightjs_Integration/extension.json"

    ...
    "ResourceModules": {
        "ext.HighlightjsIntegration": {
            ...
            "styles": [
                "custom.css",
                "highlight/styles/vs2015.min.css"  // change to another css file
            ],
            ...
        }
    },
    ...

Tags

[edit]

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

[edit]

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

[edit]

This extension is bundled with highlight.js version 11.7.0 and the 36 common languages.

Update HighlightJS

[edit]

If you want a different version of the highlight.js library or add / 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 use the bundled highlight.min.js script and not the one from CDNJS:

  • replace the content of the init.js file by the following code
hljs.configure({
    cssSelector: 'pre.code2highlight, code.code2highlight, pre.mwcode'
});

hljs.highlightAll();
  • update the extension.json file by adding highlight/highlight.min.js in the scripts to load in this extension
"ResourceModules": {
    "ext.HighlightjsIntegration": {
        "scripts": [
            "highlight/highlight.min.js",
            "init.js"
        ]
    }
},

Adding external libraries to handle additional languages

[edit]

Some languages are not available in highlight.js but you can add external libraries to handle additional languages.
Here is the list of all supported languages, the ones with a package name are external which need to be installed.

Installation of the T-SQL language grammar for highlight.js:

  1. download the tsql.min.js and ssms.min.css from the highlightjs-tsql GitHub repo
  2. copy the files to the extensions/Highlightjs_Integration/highlight folder
  3. update the extensions/Highlightjs_Integration/extension.json file
extensions/Highlightjs_Integration/extension.json
{
    // ...
    "ResourceModules": {
        "ext.HighlightjsIntegration": {
            "scripts": [
                "highlight/highlight.min.js",
                "highlight/tsql.min.js",      // add the javascript file for the T-SQL language
                "init.js"
            ],
            "styles": [
                "custom.css",
                "highlight/styles/vs2015.min.css",
                "ssms.min.css"               // add the css file for the T-SQL language if any
            ]

Bug Uncaught SyntaxError: unterminated regular expression literal

[edit]

This is a know bug with highlight.js version 11.5.1, it is not an issue with version 11.7.0 anymore.

The load of the highlight.min.js script in this extension raises a syntax error.
As a workaround, the highlight.min.js script is loaded from the CDNJS url instead of the file provided with this extension.

See also

[edit]