I started out using Markdown like everyone else — blissfully typing asterisks and hashes, pretending it was enough. And for a while, it was. I mean, it’s fast, it’s everywhere, and it gets the job done for short notes, READMEs, and the occasional blog post if you’re okay with everything looking like a GitHub issue. But then I tried writing a long technical post. I wanted nested lists, code blocks with proper highlighting, maybe an info box or a callout. And suddenly Markdown started to feel like trying to build a house with nothing but duct tape and a stick. I ended up Googling "markdown table syntax" every 20 minutes, bolting on plugins, escaping things manually, and rage-writing HTML inside Markdown like some kind of markup Stockholm syndrome.
Enter AsciiDoc. I found it while doomscrolling through docs and decided to try it out. And honestly? It’s Markdown’s older sibling who went to grad school. Tables are clean. Callouts are native. TOC? One line. Metadata? Built-in. Code block styling? Easy. Custom attributes? You bet. I don’t have to fight it to make it look good. It’s not just a formatting tool — it’s a language for writing actual structured documents. Plus, asciidoctor spits out pure, semantic HTML, supports PDF/EPUB generation, and doesn’t need 200 dependencies just to not break. The fact that I can drop in a single CSS file, add dark mode support with prefers-color-scheme, and have the whole site build with one shell script? Chef’s kiss.
Now, whenever someone says “but Markdown is simpler,” I nod politely while quietly editing my .adoc file in peace, knowing that if I ever want to footnote, nest, style, or publish anything that doesn’t look like a glorified plain text file, I made the right call. Markdown is fine — until it’s not. AsciiDoc is a power move. And honestly, it just hits different.