Feb 5, 2025

Asciidoc

I’m using markdown a lot for it’s simplicity and a lot of software can use it. But it has some drawbacks, there are walkaround for some cases but still :

markdown (md) is not made for large documents
you cannot make good diagrams in markdown
i often forget the html link syntax
the syntax for image is not clear
code block is not clear
doesn’t handle variables
you have to rely on html sometimes

So i’m currently making a switch to a better "doc as code format". I’ve chose asciidoc which overcome those drawbacks and is very similar to markdown. And of course is supported by my cms hugo so i can use both if needed.

Here are some examples of the benefits of asciidoc :

you can write large documents with many different parts
you can easily write good diagrams like this one

I don’t have to rely on html at all
Code blocks are clear

How to enable on HugoCMS :

To enable asciidoc on markdown add the following to your config file :

[security.exec]
allow = ["^asciidoctor$"]
[markup]
  [markup.asciidocExt]
    backend = 'html5'
    extensions = ['asciidoctor-diagram']
    failureLevel = 'fatal'
    noHeaderOrFooter = true
    preserveTOC = false
    safeMode = 'unsafe'
    sectionNumbers = false
    trace = false
    verbose = false
    workingFolderCurrent = true
    [markup.asciidocExt.attributes]