asciidoctor-prism-extension

asciidoctor-prism-extension

Highlight Asciidoc code listings with Prism.js, server side, with no front-end dependencies.

This module is intended to be used with Asciidoctor.js, and Node.js (v10+). It adds a new syntax highlighter, to be used when converting Asciidoc to HTML5 documents. The syntax highlighting happens during the document conversion.

Install

$ npm install @asciidoctor/core asciidoctor-prism-extension

Configure

Register the extension

const asciidoctor = require('@asciidoctor/core')();
const prismExtension = require('asciidoctor-prism-extension');

asciidoctor.SyntaxHighlighter.register('prism', prismExtension);

Change the rendering

This extension relies on Asciidoc attributes to affect the theme and the highlighted syntaxes.

= Document
:source-highlighter: prism
:prism-languages: bash,docker,jsx

...

Attribute	Default	Possible values
prism-theme	prism.css	Any filename in this list.
prism-languages	asciidoc,bash,json,markdown,typescript,yaml	Any supported language.

Theme can be disabled with the negated attribute (! character):

= Document
:source-highlighter: prism
:prism-theme!:
:prism-languages: bash,docker,jsx

...

Render document

Then you convert as usual:

asciidoctor.convertFile('document.adoc', {
  to_file: 'document.html',
  backend: 'html5'
});

Note: attributes can be specified at this stage too. Have a look at Asciidoctor.js API to learn more about it.

Use

Author your documents as you would regularly do. The second argument of a code listing hints the language to the syntax highlighter.

In the following example, yaml is going to be used to colour the output:

[source,yaml]
.example.yml
----
language: node_js
node_js: node

script: npm test
----

About

Prism

Prism is a highly configurable syntax highlighter.

License

MIT.