Highlighting source code

Source highlighting shows source code listings in a document colored for better readability similar to an IDE. The preview supports different highlighting for source code like Coderay, Rouge and highlight.js. The plugin supports this both for the JCEF and the JavaFX preview modes.

How to use source highlighting

Source highlighting in the preview works best when JCEF or JavaFX are selected in the plugin’s settings as the preview browser.

Once a document contains a code block marked with a language that the source highlighter supports, the preview shows it highlighted.

The default highlighter for the plugin’s preview is the CodeRay source highlighter. See Configuring Source Highlighters for how to set up source highlighting when rendering documents outside the plugin, and to change the source highlighting package to support other languages or different highlighters.

Source for a minimal code block in the document with language C
[source,c]
----
#include<stdio.h>

int main() {
	printf("Hello World\n");
	return 0;
}
----
Rendered output in the preview with source highlighting
#include<stdio.h>

int main() {
	printf("Hello World\n");
	return 0;
}

Configuring Source Highlighters

The default highlighter for the plugin’s preview is the CodeRay source highlighter. To activate source highlighting with CodeRay when rendering documents outside the IDE, set the following attribute in the header of the document:

:source-highlighter: coderay

While source highlighters are configurable and pluggable in Asciidoctor, the AsciiDoc plugin for IntelliJ supports only a distinct number of source highlighters.

The following lists the values for the source-highlighter attribute supported by this plugin.

coderay

The default highlighter for the plugin’s preview. See CodeRay source highlighter for more information.

rouge

An alternative highlighter. See Rouge source highlighter for more information.

highlight.js

A syntax highlighter based on JavaScript. The plugin supports also highlightjs as an alias for the name of the source highlighter. See highlight.js source highlighter for more information.

Support for this highlighter is available since plugin version 0.32.50, earlier versions include only partial support. The plugin pre-bundles the common languages as listed on highlight.js' download page plus AsciiDoc.

The plugin supports the attributes highlightjsdir, highlightjs-theme and highlightjs-languages. Attributes highlightjs-theme and highlightjs-languages are only supported when a highlightjsdir has been specified, and the necessary files are available.

Valid values for the attribute highlightjsdir are:

  • A URL starting with either http:// or https://,

  • a local directory with an absolute path within the current project, or

  • a relative directory from the project’s root folder.

An example configuration for a local configuration could look like this:

Configuration of highlight.js files in the local project
:source-highlighter: highlight.js
:highlightjsdir: hljs (1)
:highlightjs-theme: default (2)
:highlightjs-languages: basic (3)

[source,basic]
----
10 PRINT "HELLO WORLD"
20 GOTO 10
----
1 If the user specifies the attribute highlightjsdir, they must place the JavaScript bundle and a theme in the current project. For this example, the JavaScript bundle must be named /hljs/highlight.min.js. See the next item for the theme.
2 If the user specifies a highlightjsdir, they can override the highlighting theme using highlightjs-theme. A CSS file matching the selected theme must be placed in the current project. If a user does not specify highlightjs-theme, the default is github and the user must place the CSS file for the github theme in the styles folder. For this example, it must be named /hljs/styles/default.min.css.
3 If the user specifies a highlightjsdir, the user can specify additional languages for highlighting using highlightjs-languages. This requires a file for each language defined here. For this example, the user must place /hljs/languages/basic.min.js in the current project.

Users can change the default code highlighter:

  • To change this for all documents, configure attribute source-highlighter to the desired value in the plugin’s settings.

  • To change this for a single document, set the attribute source-highlighter in the document.

  • To change this for all documents in a folder or within a project, set the attribute source-highlighter in an Asciidoctor Config File.

More Information

Read more about source highlighting in the AsciiDoc documentation.