escaping certain constructs is more painful:.slightly more complex, due to more features.less commonly used as of 2019, so slightly higher entry barrier.> inserts the human readable header title of the given ID by default

This is also a major source of style divergence in Markdown, since there are so many ways to achieve the same HTML output, e.g.: Spaces after list marker GitHub even added the triple backticks block code extension syntax because of that!

not possible to view older versions of the documentsīuilt-in syntax can link to headers, give headers custom IDs independent of text, and with asciidoctor -v get a warning for broken linksĮverything can be done without indentation, which is hard to type on browser boxes.broken builds on forced dependency updates.forget about GitHub Pages difficulties such as:.sed refactors everything if you use a single source file.This allows you to easily put everything one HTML page or source file. Here is one example of what you can achieve on GitHub with a README.adoc: Īnd here is Buildroot’s perfect AsciiDoc-based generated documentation:ĪsciiDoc has built-in Table of Contents and file inclusion functionality. The Asciidoctor implementation is likely the best choice as of 2019.ĪsciiDoc takes Markdown, and adds just enough to write serious books, while reducing some markdown annoyances at the same time.

your document is large enough to need a headerĬonsider using AsciiDoc instead of Markdown.

GitHub READMEs, self-rendered documentation Readable and portable Markdown style guide. Markdown Style Guide - Ciro Santilli Ciro Santilli Markdown Style Guide

Set macdown default to open md file