Newer posts are loading.
You are at the newest post.
Click here to check if anything new just came in.

Random Thoughts about AsciiDoc

A question on Twitter made me quite curious about AsciiDoc. I’ve heard about it in the past and as someone writting almost everything in Markdown I was naturally curious to see what improvements could it bring to my environment.

What follows is the series of remarks, comments, head scratchers, and complains I accumulated over a couple of hours of learning AsciiDoc:

  1. searching anything about AsciiDoc led me invariably to either AsciiDoc or Asciidoctor. That was confusing as hell. Even if the 2 projects seem to be related.
  2. after doing quite a bit of reading, I still cannot summarize the main advantages of AsciiDoc when compared with Markdown. I did noticed some interesting features, but I had to read the docs twice. Now when writting this, I do realize that I should’ve create that summary myself.
  3. I didn’t find a way to simply generate an HTML fragment; AsciiDoc supports multiple output formats, but not HTML fragments (see update at the end)
  4. it feels to me that AsciiDoc has a bit too much ceremony. While I did look at an example file, I failed the test of creating a simple document right after going through the docs.
  5. I have found an AsciiDoc plugin for Vim that is quite good. Spacemacs also has a layer for AsciiDoc, but the formatting used goes too far and I could hardly use it.
  6. weirdly enough, while AsciiDoc has better support for standardizing quotations (inline and block), I have discovered that when generating HTML, it doesn’t use either of the specialized tags cite or blockquote. I have found a corresponding ticket from 2013.

In the times of myNoSQL, I have developed my own toolkit and extensions around various Python libraries, starting with Markdown and all the way to custom scripts for resizing and uploading images, and an end-to-end publishing workflow. I don’t need such a complete toolkit these days, but if I’d actually see the significant benefits of AsciiDoc, I’d probably be tempted to address some of the above points myself.

Update: thanks to Dan Allen, I’ve learned that it’s possible to generate HTML fragments by using the -s option.

Don't be the product, buy the product!