Fossil Backend for AsciiDoc

Published: 2011-08-30
Updated: 2012-09-11, 2012-08-30, 2011-09-04, 2011-08-22

The AsciiDoc Fossil backend plugin is hosted on Github, it generates Fossil friendly Wiki markup from AsciiDoc source. As of version 1.0.0 (2012-08-30) the Fossil backend plugin embeds linked images and admonition icons in the wiki documents.

The backend itself is a single fossil.conf configuration file.

To install the Fossil plugin download fossil.zip and install it with AsciiDoc (you will need AsciiDoc version 8.6.6 or newer):

asciidoc --backend install fossil.zip

Use the fossil backend as you would the built-in backends then pipe the output into Fossil. For example, this command will create a Wiki page called AsciiDoc in the current Fossil repository:

asciidoc -b fossil -a iconsdir=./icons -o - asciidoc.txt | fossil wiki create AsciiDoc

This command updates the existing wiki page:

asciidoc -b fossil -a iconsdir=./icons -o - asciidoc.txt | fossil wiki commit AsciiDoc

Note	Specifying the location of the admonition icons by setting the iconsdir attribute has been rendered unnecessary by a commit made on 11-September-2012.

Fossil Fossil is a wonderful distributed version control system (DVCS) by Richard Hipp, the author of SQLite. It is built on SQLite and shares the same small-is-beautiful single stand-alone executable philosophy. A Fossil repository doesn’t just manage source, it also supports distributed project bug tracking, wiki and blog — all managed by an integrated Web UI.

Note

By default linked images and admonition icons will be embedded in the wiki documents using the data URI scheme (AsciiDoc data-uri and icons attributes are set in the plugin’s fossil.conf file). Older browsers (notably IE8) limit the size of data URIs. You will need AsciiDoc version 8.6.6 or newer to use the Fossil backend. To update an existing wiki page use the Fossil wiki commit command (not wiki create).

Wiki HTML limitations By default the Fossil wiki formatting rules enforce an HTML subset. If you want richer HTML wiki pages you could enable the Fossil Use HTML as wiki markup language configuration option, but this is not advisable because: Malicious users could inject dangerous HTML, CSS and JavaScript code into your wiki. It is not a supported option. Wiki links [...] are translated to HTML links which in turn precludes the use of HTML embedded script and style elements. Keep in mind that wikis are designed to allow casual users to enter short relatively simple notes. Project documentation (which is often longer and more complex) is usually better served using Fossil’s Embedded Documentation feature. Another gotcha is that currently the Fossil web server does not follow symlinks, instead it displays the content of the symlink file.