Converting from AsciiDoc to Google Docs and MS Word

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 howIlove Markdown but I’ve actually moved on from that and now firmly throwmy hat in the AsciiDoc ring. I’llwrite another post another time explaining why in more detail, but inshort it’s just more powerful whilst still simple and readable withoutcompilation.

So anyway, I use AsciiDoc (adoc) for all my technical (and oftennon-technical) writing now, and from there usually dump it out to HTMLwhich 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 easiersharing)

But today I needed to generate a MS Word (docx) file, and found a neatcombination 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 bysetting --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

Use pandoc --list-highlight-styles to get a list of availablestyles. You can also customise a theme by writing it to a file(pandoc --print-highlight-style pygments > my.theme), editing thefile (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 whatabout other styles that you want to customise? Perhaps you want tochange the formatting used for code that’s inline in a paragraph too,not just blocks. To do this with .docx output from pandoc you usethe --reference-doc parameter, and pass in a .docx file with thestyles set up as you want.

To create a .docx file with all the styles that pandoc may use intranslating 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 definitionsas required

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

Converting Asciidoc to Google Docs format

Using the above process is the best way I’ve found to write content inasciidoc 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 meanthat if Google Docs is your preferred collaboration & review tool youcan still prepare your content in asciidoc.

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

References

• Asciidoctor

  • On the mac: brew install asciidoctor

• Pandoc

  • On the mac: brew install pandoc

• AsciiDocextension for VS Code

  • VSCode is my new favourite editor (but I still ❤️ emacs for org-mode)