Compare AsciiDoc and Markdown

submited by
Style Pass
2021-07-06 05:30:04

The most compelling reason to choose a lightweight markup language for writing is to minimize the number of technical concepts an author must grasp in order to be immediately productive. In other words, the goal is to be able to write without friction.

The defacto lightweight markup language is Markdown. (At least, Markdown is what you call it at first). The main advantage of Markdown lies in its primitive syntax: its manual and cheatsheet are one and the same. But this advantage is also its greatest weakness.

As soon as authors need something slightly more complex than basic prose (e.g., tables, cross references, footnotes, embedded YouTube videos, etc.), they find themselves resorting to embedded HTML or seeking out more feature-rich implementations. Markdown has become a maze of different implementations, termed “flavors”, which make a universal definition evasive.

Here’s how the story inevitably goes. You start out with Markdown. Then it’s Markdown + X. Then Markdown + X + Y. And down the rabbit hole you go. What’s worse, X and Y often require you to sprinkle in HTML, unnecessarily coupling content with presentation and wrecking portability. Your instinct to choose Markdown is good. There are just better options.

Leave a Comment