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.