Palabra Technical

Automating docs-as-code to Google Docs conversion

Palabra Technical
3 Mins
technical-writing
bash script for pandoc conversion

A challenge of maintaining docs-as-code is organizing comments and feedback.

It is inconvenient for team members to download a repo and comment directly in the markdown. Tools for commenting directly in the browser can be hit-and-miss. Besides, team members will appreciate using familiar tools rather than introducing new ones.

A solution is Pandoc to convert markdown to Google docs. This article will show simple shell scripts to bulk convert markdown files for Google Drive.

Background

What is docs-as-code?

With docs-as-code, documentation is managed in the same way as a code. This involves:

  • Writing content with markdown files in an IDE
  • Version control system to store and version it
  • Automated testing
  • Build and deploy system

What is Pandoc?

Pandoc is described as the “swiss-army knife” for converting files from one markup format into another.

It supports conversion to/from dozens of formats: lightweight (e.g., md, emacs); word processor (e.g., docx, RTF); eBooks, TeX, PDF, etc.

It includes a Haskell library and is mostly used as a standalone command-line program. Pandoc is free, released under the GPL.

Conversion

Bulk converting markdown files to Google Docs simplifies the review process. Of course, one option is simply pulling the markdown directly into Google Drive. However, file conversion is preferable if you want to preserve headers, formatting, images, etc.

The following are steps for converting a directory with subdirectories containing markdown files.

  1. Install pandoc: brew install pandoc.

  2. Make a copy of the directory you want to convert. cd into that directory (e.g., Documents/docs/).

    The next 3 steps create separate shell scripts for demonstration. They would normally be combined into one.

  3. If your markdown contains relative links to images, you’ll need to change them to absolute paths.

    In the example below, the images are linked in the markdown file with the relative path /assets/images/.... The example below replaces with the absolute path /Users/user/assets/images/.... vi convertLinks.sh:

       #!/bin/bash
   for dir in ~/Documents/docs/*; do
     for sub in /$dir/*.md /$dir/*/*.md; do
     #replace links
     sed -i.bak 's#(/assets/images/#(/Users/user/assets/images/#g' $sub
     done
   done


  4. For the conversion, we can loop through the directories and convert md files to the desired format. Here, we convert each to a docx with the same name. vi convertFiles.sh:

       #!/bin/bash
   for dir in ~/Documents/docs/*; do
     for sub in /$dir/*.md /$dir/*/*.md; do
     pandoc $sub -f markdown -t docx -s -o ${sub%.*}.docx
     done
   done


  5. Finally, delete the bak and md files. vi delete.sh:

       #!/bin/bash
   for dir in ~/Documents/docs/*; do
     for sub in /$dir/* /$dir/*/*; do
     rm ${sub%.*}.bak
     rm ${sub%.*}.md
     done
   done


Running the above scripts:

./convertLinks.sh && ./convert.sh && ./delete.sh

will result in a directory with only docx files that you can upload directly to Google Drive.

folder with only docx files.

Google Drive

Before moving the folder to Google Drive, select the setting “Convert uploaded files to Google Docs editor format”.

convert to Google Drive format

Then upload your folder and share for commenting.

Once edits have been made, you can use a similar process to convert back to markdown.

Share