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 [d2] .... direction: right Markdown -> Asciidoc: shift to .... * 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 : [source, toml] ---- [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] ----