> how is it better (superior) than markdown? In nearly every way. It has been thought out properly from the start. If you want to do something a little bit advanced it has an elegant solution. Here is just a list off the top of my head: - Precise image placement - Document pre-processor (similar to YAML but more powerful) - Table of Content - Great bibliography support and footnotes - Embeds backed in - Good referencing syntax - Admonition sections - Precise image placement - Proper syntax for quoting people - Add containers easily to each section - Plugins to generate nice semantic HTML (very easy to theme with CSS) - You can use it to write a book - Did I mention precise image placement? A quick intro is here: https://asciidoctor.org/docs/what-is-asciidoc/ More detailed guide here: https://asciidoctor.org/docs/asciidoc-writers-guide/ Both pages are written in normal AsciiDoc (i.e. no extra plugins are used. It is what you get out of the box) and use the "default" HTML output.