asciidoc

How to use a non-default table column separator in Asciidoc

As a brief note, if you ever need to use a different column separator when creating a table in Asciidoc, you can do so by specific the separator field in the table preamble.

For example, in the following Asciidoc table I can’t use the default pipe character | to separate the table columns, because I need to use that character in the content inside the table, so I set the separator character to be : instead:

<<methods_to_combine_cmds>> lists the ...

.Methods to combine external commands
[[methods_to_combine_cmds]]
[cols=",",options="header",separator=:,]
|===============================
:Methods :Description
:`cmd1 #| cmd2`  :The output of the first ...
:`cmd1 ### cmd2` :`cmd1` and `cmd2` will be ...
:`cmd1 #> cmd2`  :Normally used to write to ...
:`cmd1 #&& cmd2` :Run `cmd2` if `cmd1` runs ...
:`cmd1 #|| cmd2` :Run `cmd2` if `cmd1` ...
:`cmd1 #&& cmd2 #|| cmd3` :Run `cmd2` is ...
|===============================

I shortened that content so you don’t have to read through all the non-essential text, but the image shows the actual resulting Asciidoc table.

For more information, this asciidoctor.org URL was the most helpful resource for me. This other page shows how you can specify format="csv" to create a table from a CSV-style syntax.

In summary, if you needed to see how to create an Asciidoc table with a non-default table column separator, I hope this example is helpful.

A little Scala project to convert AsciiDoc to clean, simple HTML

Table of Contents1 - A shell script solution2 - A JavaFX GUI3 - Summary

I recently started using AsciiDoc to write a new book. A great thing about it is that unlike Markdown, you can use AsciiDoc to write a book and get all of the features you want in a book, including linking between anything, captions for tables and figures, indexes, etc. Because this got me started using AsciiDoc I thought, “Wouldn’t it be nice if I could also use AsciiDoc to write blog posts like this one?”

Sadly, I quickly ran into a problem: I couldn’t find a good way to convert AsciiDoc into HTML, or even Markdown. There are tools to convert AsciiDoc to HTML, but for some reason they take the approach of including a ton of markup in the HTML (divs, spans, and attributes), and as far as I can tell there’s no way to turn off that markup.

How to convert asciidoc to markdown

It turns out that converting AsciiDoc to HTML without including a bunch of undesired CSS is a problem, and converting AsciiDoc to Markdown is also a problem. The page I linked to shows the best way I’ve found to convert AsciiDoc to Markdown, which can then be converted to CSS-free HTML. In case that page ever disappears, the basic commands are:

Install pandoc and asciidoc:

sudo apt install pandoc asciidoc

Convert asciidoc to docbook:

asciidoc -b docbook foo.adoc

Convert docbook to markdown:

How to convert Docbook to AsciiDoc

If you ever need to convert Docbook to AsciiDoc, this Pandoc command seems to work well:

pandoc --wrap=none -f docbook -t asciidoc \
       DocbookFile.xml > AsciiDocFile.adoc

How to convert HTML to AsciiDoc with Pandoc

If you ever need to convert HTML to AsciiDoc, I just used this Pandoc command and it seems to work well:

pandoc --wrap=none -f html -t asciidoc myfile.html > myfile.adoc

The wrapping part of that command isn’t 100% necessary, but if you don’t use it, Pandoc will wrap the plain paragraph text, which I don’t like because I’ll be editing the resulting AsciiDoc text.

Here’s some of the AsciiDoc text that this command generated:

How to convert Asciidoc to HTML

As a brief note to self, if you need to convert an Asciidoc file named test1.adoc to HTML format, this command works:

asciidoc -o test1.html test1.adoc

Of course a key here is that you need the asciidoc command installed. I installed it on my Mac with Homebrew, something like brew install asciidoc. I don’t like the HTML that this approach generates, so I’ll keep looking for something better.