Converting from AsciiDoc to Google Docs and MS Word
Tags: asciidoc, pandoc, googledocs
Published: 2020-04-17 09:05:13

---
title: Converting from AsciiDoc to Google Docs and MS Word
published: true
date: 2020-04-16 00:00:00 UTC
tags: asciidoc,pandoc,google docs
canonical_url: https://rmoff.net/2020/04/16/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 how[Ilove Markdown](https://rmoff.net/2017/09/12/what-is-markdown-and-why-is-it-awesome/) but I’ve actually moved on from that and now firmly throwmy hat in the [AsciiDoc](http://www.methods.co.nz/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
```

![image](https://rmoff.net/images/2020/04/docx.png)

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

![image](https://rmoff.net/images/2020/04/docx1.png)

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](https://rmoff.net/images/2020/04/docx2.png)

## 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''

![image](https://rmoff.net/images/2020/04/adoc_to_google_docs.png)

## References

- [Asciidoctor](https://asciidoctor.org/)

  - On the mac: `brew install asciidoctor`

- [Pandoc](https://pandoc.org/)

  - On the mac: `brew install pandoc`

- [AsciiDocextension for VS Code](https://marketplace.visualstudio.com/items?itemName=joaompinto.asciidoctor-vscode)

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