Using AsciiDoc and Asciidoctor for Blogging | Hacker News Reader

Using AsciiDoc and Asciidoctor for Blogging

duncanlock.net

73 points_xivi19 comments

I'd like to see a comparison to Pandoc. The only reason he gives for all of this AsciiDoc mess is to get "Figure/Images with captions / Admonitions / Front-matter/Metadata / Footnotes", but 3 of those are available in Pandoc out of the box, and the fourth is easy to roll your own, as I have done. (Admonitions are just a div and an admonition class; certainly nothing so complex that you want an entire document tool chain just to do the same thing.)

pandoc is a format converter, not a format. You still need to write the document. That said, I would rather choose something pandoc supports as an input format than asciidoc, which is a constantly moving target that still doesn't have a specification, is governed by a working group that seemingly never makes decisions, and in practice asciidoctor may as well be the specification.

As an addendum to yesterday's discussion of software estimates, one of the more amusing open source versions is this guy saying in July of 2014 he expected pandoc's asciidoc frontend to be done in a "few months": https://github.com/jgm/pandoc/issues/1456#issuecomment-50805...

Pandoc supports asciidoc. I have used it to convert from .adoc to.md

Are you sure? Recent GH issues say that it can write .adoc, but cannot read it.

> You still need to write the document.

Note that OP does not suggest that he should write in AsciiDoc because he loves the syntax so much; in fact, (in addition to a bunch of complaints about confusing AsciiDoc syntax) he winds up saying that you should write your AsciiDocs essentially like they are Markdown with a handful of unavoidable AsciiDoc constructs to get the benefits of tooling/syntax-highlighting. If he thought AsciiDoc was so much nicer to write in, syntactically, he should've been clearer about that and included it in the intro list of 'why AsciiDoc' reasons I quoted.

So, that is not an answer to my question of 'why not just use Pandoc + a little bit of custom CSS?'

When I started developing KeenWrite[1], I wanted a modular architecture[2] that made the choice of Markdown vs. AsciiDoc vs. DocBook irrelevant with respect to generating PDF or HTML files. The core idea of writing pure text documents is to separate content from presentation; the syntax, while important to some, shouldn't sway the output format.

KeenWrite could integrate AsciidoctorJ and its XHTML5 back-end to support AsciiDoc in the future, if there was demand.

[1]: https://keenwrite.com/

[2]: https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/imag...

Ursus too! It would be fairly trivial. I just prefer Markdown though. I edit content for a living and Markdown is rock-solid.

https://github.com/nicbou/ursus

There's Asciidoctor.js that works nicely. I'm not so sure if any mainstream static site generator work well with it, but a lot of Asciidoc blogs do use custom implementations of it with simple scripts.

There's Antora which is... sort of an SSG, built around asciidoctor source. I say sort of because it's really meant for compiling documentation for code (git is a built-in concept), but it's not hard to finagle it into acting like a regular SSG that you'd use for blog posts.

I'm pretty sure Hugo supports asciidoc.

Yes it does

I use asciidoctor (via a simple filter for the nanoc static site generator[1]) for my weblogs. It works especially well for footnote-heavy essays[2] (at least compared to my attempts to use various markdown flavors for blogging), and also for code snippets[3]

1: https://nanoc.app/ 2: example: https://americancynic.net/log/2018/12/3/kivas_interest_rates... 3: example: https://catswhisker.xyz/log/2020/12/7/deranged_sinterklaas/

I use Markdown for footnote-heavy content and it works fine. A Sublime Text plugin makes it very smooth.

I really like asciidoc as an alternative to markdown, but it seems like the only preprocessors are written in JavaScript & Ruby, which limits where/how I can use it

I've been watching asciidoc for quite awhile. It looks excellent for its features, but its biggest problem is that every time I investigate it, it looks like in a year it's gonna be usable.

What obstacles do you experience with it? I've used it for years in a professional setting for technical documentation, about 9 years ago. It worked fine for our purposes.

Oh wow, just look at that fansy premble region. Not a div soup, but an actual HTML element, that gets read by a screen reader. May this new HTML backend soon become the default!

I use asciidoctor and jinja2 to generate PDF reports at work. Works pretty well, the syntax is a lot less cryptic than LaTeX.

Anyone done a bare-bones turnkey Asciidoc blog with Tufte CSS for semantic HTML including side margin footnotes ?

Reply on news.ycombinator.com