asciidocjs Plugin

External requirements: This plugin can make use of the following additional component if it is installed separately:

• node.js

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

The plugin allows the write pages using asciidoc markup in DokuWiki. Therefore it supports two syntax elements:

and

With <asciidoc>…</asciidoc> it is possible to mix blocks formatted using asciidoc with other blocks resulting in a document which mixes DokuWiki and ascidoc syntax.

The marker //#--asciidoc--#// should only be used at the beginning of a document and only asciidoc markup should be used afterwards. Since this marker is a comment in asciidoc the resulting DokuWiki file is therefore a valid asciidoc file. There is no way to exit the asciidoc mode when this pattern is used.

A description of the AsciiDoc markup language can be found at AsciiDoc Language Documentation

Basic syntax:

<asciidoc>...</asciidoc>

• The text in the block should use asciidoc markup language.

//#--asciidoc--#//

• The marker at the beginning of a file marks the whole file as an asciidoc file

Wikilink:id[text]

• The asciidoc inline macro Wikilink creates a link to a DokuWiki page wpecified by its id with the display text given as a parameter. If the parameter is empty ([]) then the id is used as the display text.

The Plugin has the following configuration options:

• Include the AsciiDoctor CSS file
• Asciidoctor safe mode (see Safe Modes)
• Processing of the asciidoc to html conversion (browser or server)
• Path to the node.js executable
• Use Kroki Extension for AsciiDoctor (see https://github.com/ggrossetie/asciidoctor-kroki)
• Url of the kroki-server to be used

The AsciiDotor CSS file might interfere with the CSS file of the template. Its usage can be disabled.

The conversion between asciidoc and html5 can be done either in the browser or by the server. If the conversion in the browser is selected then the plugin will create a json script based on the asciidoc markup text and embeds this script in the html page. AsciiDoctor.js is used on the client side in the browser to convert the embedded asciidoc markup scripts to html, which is injected in the DOM of the browser.

The conversion from asciidoc to html5 is only possible on the server side if node.js is installed on the server. The plugin will then run node.js with AsciiDoctor.js to convert the asciidoc markup to html and sends then a pure html page to the browser.

The default command to run node.js is node. If needed the command to execute node.js can be adjusted in the configuration.

Node.js is needed to generate pdf pages with DW2PDF if the asciidocjs plugin is used. Manually erase the path to the node.js executable in the plugin configuration if node.js is not installed but the plugin DW2PDF is installed.

The asciidoc extension to use a Kroki server for the conversion of images is integrated but can be disabled. In addition a name of a Kroki-server can be given which will be used instead of https://kroki.io.

The source code of the plugin is available at GitHub: https://github.com/hfr/dokuwiki-plugin-asciidocjs.

• v1.1.3 fix typo
• v1.1.2 bugfix
• v1.1.1 bugfix
• v1.1.0
• v1.0.0-beta

Complete testing and validation is needed.