Extension:Highlightjs Integration
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 | GitHub: Note: 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 yourextensions/
folder. - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'Highlightjs_Integration' );
- Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Usage
editOnce installed, you can use the syntaxhighlight
or the source
tags on wiki pages:
<syntaxhighlight>
<?php
// some php code
</syntaxhighlight>
Parameters
editlang
editIf 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
editThe 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
editStyle
editThe 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
editBy 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
editIf 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
editThis extension is bundled with highlight.js version 11.7.0 and the 36 common languages.
Update HighlightJS
editIf you want a different version of the highlight.js library or add / remove languages:
- go on the download page of the highlight.js website and download a custom package.
- remove or rename the
extensions/Highlightjs_Integration/highlight
folder. - unarchive the custom package in
extensions/Highlightjs_Integration
. You should have a fresh newextensions/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 addinghighlight/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
editSome 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:
- download the
tsql.min.js
andssms.min.css
from the highlightjs-tsql GitHub repo - copy the files to the
extensions/Highlightjs_Integration/highlight
folder - update the
extensions/Highlightjs_Integration/extension.json
file
{
// ...
"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
editThis 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- highlight.js javascript syntax highlighter
- Related extensions:
- HighlightJS – unmaintained MediaWiki extension for highlight.js.
- SyntaxHighlight – server-side syntax highlighter that uses Pygments.