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
You can customise the syntax highlighting used for code sections bysetting
--highlight-style when calling
asciidoctor --backend docbook --out-file - $INPUT_ADOC| \ pandoc --from docbook --to docx --output $INPUT_ADOC.docx \ --highlight-style espresso
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
asciidoctor --backend docbook --out-file - $INPUT_ADOC| \ pandoc --from docbook --to docx --output $INPUT_ADOC.docx \ --highlight-style my.theme
--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
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
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''