Hacker News Reader

Comment by ipnon | Hacker News Reader

From a theoretical perspective, it would be nicer to have a "programming" language for writing modern, online books than to have a Markdown compiler for the same purpose, because Markdown is not a programming language. Markdown has no authoritative definition. It's more like a family of similar HTML macro collections.

View on HN

I recently switched from Markdown to AsciiDoc. It is much better in my opinion. The syntax is similar enough to MD that just having the adoc cheatsheet bookmarked is enough to switch. But it's more structured, much more fully featured, just two big implementations (AsciiDoc and AsciiDoctor) which are largely compatible. There's only one way to mark the language of a code block, only one way to make lists, only one way to make footnotes, etc. Also it actually has first-class support for things like footnotes and admonitions[0] etc.

It is a syntactic sugar layer on the DocBook XML format which is apparently used to make actual books. But AsciiDoctor compiles it to everything from DocBook XML to HTML to Markdown to ePub to PDF.

Another thing I like is that AsciiDoctor actually comes with a good default stylesheet. If you just turn MD into HTML you get ugly garbage and need to figure out how to put CSS into the HTML etc. AsciiDoctor has a good default theme as well as a number of other themes available[1], and by default will embed the CSS into the HTML so you just have one file to distribute. It even shows anchor links to the headings when you hover over them.

[0]: https://asciidoctor.org/docs/asciidoc-writers-guide/#admonit...

[1]: this made it easier for me to add the themes, and includes more beyond the ones bundled with adoc: https://github.com/darshandsoni/asciidoctor-skins

https://docs.racket-lang.org/pollen/ "Pollen: the book is a program"

What do you think of https://mdxjs.com ?

Reply on news.ycombinator.com