Sheepshaving with Markdown and Asciidoc

After my dalliance with Markdown and Slidy I got interested in modifying the CSS used by Pandoc to generate the Slidy docs to be more like our corporate style. (our house style is very minimalist - deliberately so to make sure it displays on all devices more or less the same - basically a top strap and a bottom strap, kinda like this:

which should not be too difficult to turn into css, even if the last time I wrote any serious css was six or seven years ago.

So, I started looking for some examples where people had modified the default css files used by pandoc and in the process happened across asciidoc as an alternative lightweight markup language.

Actually I'll rephrase that - asciidoc is a medium weight markup syntax. You can teach anyone who can use an editor markdown in ten minutes (and you can teach anyone to use an editor - providing it's not vi - well enough to write markdown in 10 minutes).

Asciidoc is that bit more complex and probably takes a couple of hours to teach or a dedicated wysiwyg tool. Like TeX, and unlike Markdown, the formatting is slightly more abstract than the immediacy of Markdown, meaning people need to think more about the structure of what they are writing, rather than bash it out and fix it later.

Anyway. Asciidoc also has a slidy backend and accompanying css file so I thought I'd look at it for comparison.

And I got diverted. Asciidoc does some other output formats from pandoc and I got to wondering if I could feed markdoen through asciidoc to make something else. It turns out you can with the help of the alternative asciidoc.conf from the Asciidoctor project. It's not quite perfect but it creates reasonable html output from short markdown documents.

Creating slidy output from my optimised for pandoc document is not quite so reasonable but you can see it would be fixable.

Not surprisingly the replacement configuration file is really not much more than a lot of

s/this/that/g

statements with a bit of inline processing. Now I've written a lot of specialist one-off text document conversion filters in my time, and one of the problems I've come across is getting documentation onto a wiki server as wiki markup syntaxes all differ.

Markdown basically does everything in terms of formatting a wiki markup system does. So I think I'm going to write myself a little markdown to wikidot converter - been looking for an excuse to write some python ...

Written with StackEdit.