====== asciidocjs Plugin ======

---- plugin ----
description: Use asciidoc in DokuWiki
author     : Rüdiger Kessel
email      : ruediger.kessel@gmail.com
type       : syntax
lastupdate : 2023-09-24
compatible : Jack Jackrum
depends    : 
conflicts  : 
similar    : 
tags       : asciidoc, markup

downloadurl: https://github.com/hfr/dokuwiki-plugin-asciidocjs/zipball/master
bugtracker : https://github.com/hfr/dokuwiki-plugin-asciidocjs/issues
sourcerepo : https://github.com/hfr/dokuwiki-plugin-asciidocjs/
donationurl: 
----

===== Installation =====

:!: **External requirements:** This plugin can make use of the following additional component if it is installed separately: 
  * [[https://nodejs.org/|node.js]]

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

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


^  //Block-mode://  |
|  ''<asciidoc>''\\ ...\\ ''</asciidoc>''  |
and 
^  //Whole or partial page//:  |
|  ''<nowiki>//#--asciidoc--#//</nowiki>''  |


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 ''<nowiki>//#--asciidoc--#//</nowiki>'' 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 [[https://docs.asciidoctor.org/asciidoc/latest/|AsciiDoc Language Documentation]]

===== Syntax =====

Basic syntax:
<code><asciidoc>...</asciidoc></code>
  * The text in the block should use asciidoc markup language.
\\

<code>//#--asciidoc--#//</code>
  * The marker at the beginning of a file marks the whole file as an asciidoc file

\\
<code>Wikilink:id[text]</code>
  * 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.
===== Configuration and Settings =====

The Plugin has the following configuration options:

  * Include the AsciiDoctor CSS file
  * Asciidoctor safe mode (see [[https://docs.asciidoctor.org/asciidoctor/latest/safe-modes/|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. [[https://docs.asciidoctor.org/asciidoctor.js/latest/|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 [[https://nodejs.org/|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 [[https://www.dokuwiki.org/plugin:dw2pdf|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''. 

===== Development =====

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

=== Changelog ===

~~NOCACHE~~
{{rss>https://github.com/hfr/dokuwiki-plugin-asciidocjs/releases.atom}}


=== ToDo/Wish List ===

Complete testing and validation is needed. 

===== FAQ =====