AsciiDoc configuration file for Fossil DVCS wiki HTML generation
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.asciidoc
fossil.conf

README.asciidoc

Fossil Backend for AsciiDoc

An AsciiDoc plugin for generating Fossil friendly Wiki markup from AsciiDoc source.

Installation

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

asciidoc --backend install fossil.zip

Usage

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
  • 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).

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

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:

  1. Malicious users could inject dangerous HTML, CSS and JavaScript code into your wiki.

  2. It is not a supported option.

  3. 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.