In the Unix world, we love a good fight. We’ve fought over editors (Vim vs. Emacs), we’ve fought over distros (Systemd vs. Init), and now, we fight over how to write a simple list.

Markdown: The People’s Hammer

Markdown won the popularity contest for a reason: it is the “Vim” of markup. It’s fast, ubiquitous, and stays out of your way. For a quick blog post or a README, it is unbeatable. But like a hammer, it’s not great at turning screws.

AsciiDoc: The Industrial Lathe

When you move from a blog post to a 500-page technical manual, Markdown starts to fracture. You find yourself using “HTML hacks” just to get a table to look right. This is where AsciiDoc shines.

  • Native Attributes: Want to give an image a specific width or a caption? In AsciiDoc, it’s a native syntax. In Markdown, it’s a mess.
  • Includes: AsciiDoc allows you to include:: one file into another. This is vital for “Text-smithing” large projects—you can keep your chapters in separate files and forge them together at the end.
  • Complex Tables: AsciiDoc treats tables as first-class citizens, not an afterthought.

The Verdict from the Anvil

Use Markdown for the “Shell” and “Perspectives.” Use AsciiDoc for the “Manuals.” A true craftsman doesn’t hate the hammer for not being a lathe; they just know when to switch tools.

Forged in the terminal. Refined under the anvil.