Updated 16 April 2020 to cover formatting tricks & add import to Google Docs info

Short and sweet this one. I’ve written in the past how I love Markdown but I’ve actually moved on from that and now firmly throw my hat in the AsciiDoc ring. I’ll write another post another time explaining why in more detail, but in short it’s just more powerful whilst still simple and readable without compilation.

So anyway, I use AsciiDoc (adoc) for all my technical (and often non-technical) writing now, and from there usually dump it out to HTML which I can share with people as needed:

asciidoctor --backend html5 -a data-uri my_input_file.adoc

(-a data-uri embeds any images as part of the HTML file, for easier sharing)

But today I needed to generate a MS Word (docx) file, and found a neat combination of tools to do this:

INPUT_ADOC=my_input_file.adoc
asciidoctor --backend docbook --out-file - $INPUT_ADOC| \
pandoc --from docbook --to docx --output $INPUT_ADOC.docx

# On the Mac, this will open the generated file in MS Word
open $INPUT_ADOC.docx

Customising code block highlighting 🔗

You can customise the syntax highlighting used for code sections by setting --highlight-style when calling pandoc, e.g.:

asciidoctor --backend docbook --out-file - $INPUT_ADOC| \
pandoc --from docbook --to docx --output $INPUT_ADOC.docx \
       --highlight-style espresso

image

Use pandoc --list-highlight-styles to get a list of available styles. You can also customise a theme by writing it to a file (pandoc --print-highlight-style pygments > my.theme), editing the file (my.theme) and then passing it as the argument to --highlight-style e.g. 

asciidoctor --backend docbook --out-file - $INPUT_ADOC| \
pandoc --from docbook --to docx --output $INPUT_ADOC.docx \
       --highlight-style my.theme

Customising other styles (e.g. inline code / literal) 🔗

The above --highlight-style works great for code blocks, but what about other styles that you want to customise? Perhaps you want to change the formatting used for code that’s inline in a paragraph too, not just blocks. To do this with .docx output from pandoc you use the --reference-doc parameter, and pass in a .docx file with the styles set up as you want.

To create a .docx file with all the styles that pandoc may use in translating your source asciidoc, run:

pandoc -o my-custom-styles.docx \
       --print-default-data-file reference.docx

Open my-custom-styles.docx in Word and modify the style definitions as required

image

Now add this argument to pandoc when you invoke it:

asciidoctor --backend docbook --out-file - $INPUT_ADOC| \
pandoc --from docbook --to docx \
       --output $INPUT_ADOC.docx \
       --highlight-style my.theme \
       --reference-doc=my-custom-styles.docx

image

Converting Asciidoc to Google Docs format 🔗

Using the above process is the best way I’ve found to write content in asciidoc and then import it, with embedded images, into Google Docs. It’s not an ideal workflow (it’s solely one-way only), but it does mean that if Google Docs is your preferred collaboration & review tool you can still prepare your content in asciidoc.

Once you’ve got your asciidoc ready, you export it to docx (via the above asciidoctor & pandoc route), and then upload the .docx to Google Drive, from where you can ``Open in Google Docs''

image

References 🔗