7 ms·

Using AsciiDoc and Asciidoctor for Blogging

73 points by _xivi 3y ago

type0 3y ago
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.
- bobbylarrybobby 3y ago
  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.
- bitvoid 3y ago
  I'm pretty sure Hugo supports asciidoc.
  - pbhowmic 3y ago
    Yes it does
cristoperb 3y ago
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/ https://nanoc.app/ 2: example: https://americancynic.net/log/2018/12/3/kivas_interest_rates/ https://americancynic.net/log/2018/12/3/kivas_interest_rates... 3: example: https://catswhisker.xyz/log/2020/12/7/deranged_sinterklaas/ https://catswhisker.xyz/log/2020/12/7/deranged_sinterklaas/
- nicbou 3y ago
  I use Markdown for footnote-heavy content and it works fine. A Sublime Text plugin makes it very smooth.
  - deleted 3y ago
    [deleted]
gwern 3y ago
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.)
- nonameiguess 3y ago
  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-50805092 https://github.com/jgm/pandoc/issues/1456#issuecomment-50805...
  - pbhowmic 3y ago
    Pandoc supports asciidoc. I have used it to convert from .adoc to.md
    - lima 3y ago
      Are you sure? Recent GH issues say that it can write .adoc, but cannot read it.
  - gwern 3y ago
    > 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?'
rychco 3y ago
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
thangalin 3y ago
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/ https://keenwrite.com/ [2]: https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/images/architecture/architecture.png https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/imag...
- nicbou 3y ago
  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 https://github.com/nicbou/ursus
sbstp 3y ago
I use asciidoctor and jinja2 to generate PDF reports at work. Works pretty well, the syntax is a lot less cryptic than LaTeX.
darthrupert 3y ago
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.
- Lutger 3y ago
  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.
devinprater 3y ago
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!
euroderf 3y ago
Anyone done a bare-bones turnkey Asciidoc blog with Tufte CSS for semantic HTML including side margin footnotes ?

73 points by _xivi 3y ago

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.

bobbylarrybobby 3y ago
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.
bitvoid 3y ago
I'm pretty sure Hugo supports asciidoc.
- pbhowmic 3y ago
  Yes it does

cristoperb 3y ago

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/ https://nanoc.app/ 2: example: https://americancynic.net/log/2018/12/3/kivas_interest_rates/ https://americancynic.net/log/2018/12/3/kivas_interest_rates... 3: example: https://catswhisker.xyz/log/2020/12/7/deranged_sinterklaas/ https://catswhisker.xyz/log/2020/12/7/deranged_sinterklaas/

nicbou 3y ago
I use Markdown for footnote-heavy content and it works fine. A Sublime Text plugin makes it very smooth.
- deleted 3y ago
  [deleted]

gwern 3y ago

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.)

nonameiguess 3y ago
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-50805092 https://github.com/jgm/pandoc/issues/1456#issuecomment-50805...
- pbhowmic 3y ago
  Pandoc supports asciidoc. I have used it to convert from .adoc to.md
  - lima 3y ago
    Are you sure? Recent GH issues say that it can write .adoc, but cannot read it.
- gwern 3y ago
  > 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?'

rychco 3y ago

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

thangalin 3y ago

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/ https://keenwrite.com/ [2]: https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/images/architecture/architecture.png https://gitlab.com/DaveJarvis/KeenWrite/-/raw/main/docs/imag...

nicbou 3y ago
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 https://github.com/nicbou/ursus

sbstp 3y ago

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

darthrupert 3y ago

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.

Lutger 3y ago
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.

devinprater 3y ago

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!

euroderf 3y ago

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