Toxic Elephant

Don't bury it in your back yard!

A few things I don't like about AsciiDoc

Posted by matijs 11/12/2021 at 09h26

AsciiDoc is nice because a lot is possible. However, there are a lot of surprising edge cases that make it less great as an easy to read and write documentation format.

  • Some list markers support nesting, others do not

    If you use a dash (-) as a list marker, that works fine until you want to create nested lists. Then, it turns out you should be using *.

  • Outdenting lists has very weird syntax.

    To outdent a list, you have to add a number of empty lines equal to the number of outdents plus one, followed by an empty line with a +. This is too specific for a human-readable format.

  • Escaping only works where it is needed.

    Wherever an asterisk leads to bolding, you can escape it using a \ to create a literal asterisk. However, when the use of an asterisk does not lead to bolding, adding the \ will just lead to a literal \ in the output. Predicting where this will happen is tricky so you have to constantly look at the actual output.

Tags , , , no comments no trackbacks