Asciidoc Native

[gotwf]

Greetings and Salutations All You NodeBB Devs \o/

The one thing that, imho, is kind of sucky about NodeBB is Markdown. For a variety of non technical reasons Ruby, and consequently GitHub, Devs were ignorant of the existence of Asciidoc when they chose Markdown? Or maybe it was a phb top down and they did not even evaluate? Cuz if they had, I can assure you that the superiority of Asciidoc is pretty much a no brainer: Just as simple and far more expressive. Hence, authors have the advantages of simple, lean, mean markup that stays out of their creative way, but also greater expressivity for those times when they need it.

Canons loaded yet? Before we start a religious war, I suggest you go use both, exclusively, for a week each and then come back and report. You may also want to check out:

• Fedora Doc Site Overhaul

• The New Fedora Documentation Website, The Rest Of The Story

My analysis is there are lots and lots of folks who will become familiar with Asciidoc and realize how much better it is. Maybe get a bit ahead of the curve and think about offering native Asciidoc support, i.e. not relying on 3rd party module wh/may or may not be maintained over the long haul.

Thank you for your consideration.

Note: In the ultimate act of irony, GitHub uses Asciidoc for their documentation. Go figure.

[gotwf]

The case for asciidoc from the asciidoctor folks, quoted liberally from AsciiDoc vs Markdown for purposes of discussion and analysis (i.e. Fair Use):

"The defacto lightweight markup language is Markdown. (At least, that’s 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.

The IETF has declared “there is no such thing as "invalid" Markdown.” See This Is Markdown!
Or: Markup and Its Discontents.

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.

AsciiDoc presents a more sound alternative. The AsciiDoc syntax is more concise than (or at least as
concise as) Markdown. At the same time, AsciiDoc offers power and flexibility without requiring the
use of HTML or “flavors” for essential syntax such as tables, description lists, admonitions (tips, notes,
warnings, etc.) and table of contents.

It’s important to understand that AsciiDoc was initially designed as a plain-text alternative to the
DocBook XML schema. AsciiDoc isn’t stuck in a game of whack-a-mole trying to satisfy publishing
needs like Markdown. Rather, the AsciiDoc syntax was explicitly designed with the needs of publishing
in mind, both print and web. If the need arises, you can make full use of the huge choice of tools
available for a DocBook workflow using Asciidoctor’s DocBook converter. That’s why mapping to an
enterprise documentation format like DocBook remains a key use case for AsciiDoc.

And yet, AsciiDoc is simple enough to stand in as a better flavor of Markdown. But what truly makes
AsciiDoc the right investment is that its syntax was designed to be extended as a core feature. This
extensibility not only means that AsciiDoc has a lot more to offer, with room to grow, it also fulfills the
objective of ensuring your content is maximally reusable."