Hacker News new | past | comments | ask | show | jobs | submit login

Don't want to be a troll, but if you are writing anything that is not a README and/or is a book or booklet or bookish, do yourself a favor and use Asciidoc instead.



This! Asciidoc is the grown-up brother of Markdown. Designed to scale up to entire books, handle images, tables, references, citation, book indexes, maths.

And the syntax is very friendly and intuitive.


And it's quite easy to insert compiled images, e.g. Graphviz, UML diagrams, Ditaa, just by having the SOURCE in your document.


Absolutely. AsciiDoc (2002) is actually 2 years older than Markdown (2004), but is surprisingly similar to write.

It was created as an equivalent to DocBook XML for the creation of book-length technical documents. It has a rich history and is well supported in many places (try writing a README.adoc for your next GitHub-hosted repo).

It is also currently undergoing a standardization process:

https://projects.eclipse.org/proposals/asciidoc-language


What's your suggested Asciidoc toolchain?

(Pandoc will ingest Asciidoc as well as Markdown, FWIW.)


At work, we have been using Asciisoc for 10 years or so, so we use Asciidoc -> XSLT -> PDF / chunked HTML. Works great, not nice to use.

For new projects, we use Asciidoctor - it does everything but chunked HTML, and it's a pleasure to use.


Thanks.


Give me a reason to use asciidoc rather than bookdown.


I assume the person you're replying to was referring to Markdown rather than Bookdown. It seems that Asciidoc was designed for the direction which Markdown has going with all these variants. If you find yourself chasing these Markdown variants to get more flexibility, then Asciidoc might be what you're looking for.

I don't know anything about Bookdown and it may be similar to Asciidoc. I would be willing to bet that Asciidoc would be around longer than most of the MD variants though.

Why might you want to continue using MD flavors? You already have loads of MD docs and you have no control over the processes which create them (shared environment, higher-ups force you to use MD, etc.)

NOTE: If you're interested in Asciidoc, also take a look at Asciidoctor.


Thanks. That's basically what I figured.

One feature I wanted that made me go with bookdown is that the static website it creates has search builtin.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: