How to collaborate with Markdown in Google Docs and Google Drive

Technical writers, bloggers, and journalists, among others, typically collaborate with multiple people to write documents for the web. Talk to writers and they’ll often mention two very different tools: Google Docs and Markdown.

Google Docs was built for collaboration. Type doc.new in Chrome in a desktop-class browser, then select the Share button to invite other people to edit. When finished, you might download, share the link, or print the Doc. As a What-You-See-Is-What-You-Get word processor, Google Docs displays text and images as they will appear when printed.

Markdown was created for people who write for the web. Open your favorite Markdown editor, type text, and add a few web-friendly formatting indicators (e.g.: # Header, [Link](https://…), *Italic*, **Bold**, etc.). Use the add-on to preview how your text will display on the web. When finished, enter your content in a Markdown-friendly content management system or export it as HTML. Unlike a Google Doc, a Markdown file is a plain text file with both text and format commands displayed.

SEE: Google Sheets: Tips and tricks (TechRepublic download) 

You can have both the collaboration capabilities of Google Docs and the human-readable, web-friendly plain text of Markdown. Two Google Docs add-ons, Docs to Markdown and Markdown Preview, let you combine the collaboration capabilities of Google Docs to write Markdown for the web. However, these add-ons require distinctly different levels of Markdown knowledge on the part of collaborators, as described below. Additionally, at least two third-party apps–also covered below–offer the ability for multiple people to collaborate on a Markdown file, then place the finished file on Google Drive.

The following add-ons, apps, and approaches give you a variety of ways to collaborate with colleagues to make Markdown files.

Write as usual in a Google Doc, then convert

The Docs to Markdown add-on offers the ability to convert a standard Google Doc into Markdown (Figure A). People may collaborate within a Google Doc as usual: Suggest and/or make edits, add comments, save versions, and format text. Make sure to encourage your collaborators to use paragraph styles, where appropriate. For example, in this section the “Write as usual in a Google Doc, then export” is text that I selected and applied the Header 2 paragraph style. If I had simply adjusted the size and made the text bold, the Markdown export would not convert the text as a Header. 

Figure A

Open the Docs to Markdown page in the Google Marketplace to install the add-on. If you are a G Suite administrator, you may choose Domain Install, to make the add-on available to everyone in the domain, or Individual Install, to install the add-on for your own use.

When you are ready to convert a Google Doc to Markdown:
1. Open a Google Doc in a desktop-class web browser.
2. By default the add-on converts the entire document. To convert only a portion of text, select the text you want to convert.
3. Select Add-Ons, then choose Docs To Markdown, then Convert.
4. Modify any checkbox options, as needed or desired.
5. Select either the Markdown or HTML button. The system will place the converted content in the selected format within the text field below the options.
6. Place your cursor anywhere within the converted text, click, then select all of the converted content (e.g., Ctrl-A) and copy it (e.g., Ctrl-C).
7. Paste the converted text into your preferred destination (e.g., a content management system field, a plain text file, etc.).

Write Markdown in a Google Doc and preview

The Markdown Preview add-on assumes that the text within a Google Doc has been written in Markdown (Figure B). 

Figure B

As such, this add-on functions much like a preview pane in a Markdown editor. You and your collaborators will need to enter Markdown format text within your Google Doc. For example, unlike above, where you would select text and then apply the Header 2 paragraph style, you would need to write:

## Write Markdown in a Google Doc and preview

The two # tags at the start of the line indicate Header 2 in Markdown. 

For people familiar with Markdown, this approach gives you a great deal of flexibility and control. You may enter and edit text as if it is Markdown, and also have access to Google Docs’ version history and comment capabilities.

Open the Markdown Preview page in the Google Marketplace to install the add-on. If you are a G Suite administrator, you may choose Domain Install, to make the add-on available to everyone in the domain, or Individual Install, to install the add-on for your own use.

When you are ready to preview the contents of your Google Doc as Markdown:
1. Open your Google Doc in a desktop class web browser.
2. Select Add-Ons, then choose Markdown Preview, then Show Preview.
3. The system will treat the contents of your Google Doc as Markdown and display it in the sidebar to the right of your Doc.
4. Review the results. Edit your Google Doc to reflect any needed or desired changes, then repeat the process.
5. Once the Markdown Preview displays as you wish, select the contents of your Google Doc (e.g. Ctrl-A) and copy it (e.g., Ctrl-C).
6. Paste the converted text into your preferred destination (e.g., a content management system field, a plain text file, etc.).

Collaborate in a third-party app, save to Google Drive

Two third-party apps, Draft and IA Writer, also offer the ability to collaborate on a Markdown format file and then save the results to Google Drive (Figure C).

Figure C

Draft offers a web-based app with version control that provides the owner of a document complete control over whether to accept or reject all changes made by collaborators. You may export your file from Draft in Text or Markdown format to Google Drive (or several other storage services). 

The IA Writer Android app lets you connect to Google Drive as a storage source and also offers an online collaboration option. Create a new IA Writer file, choose the Android Share icon, then choose Collaborate Online. This creates a collaborative version of the file that you may open in a browser. Share the link to the file with your collaborators. All collaborators may make edits, until you choose to end sharing. When you end sharing, you’ll be prompted to save the file. You can save the edited file on Google Drive (or elsewhere). 

Other options?

Outside of Google Drive, many people use Git with various apps and services for version control of Markdown files. The scope of these setups is beyond the focus of this article, but to explore a few more technical Markdown collaboration options, see IA Writer with Working Copy, iCloud Drive, and BitBucket or Working Copy, iCloud, and GitHub (iOS and iPadOS), Typora with GitHub (Windows, Linux, and macOS), or VS Code, Jotterpad, Dropbox, and GitHub (Windows and Android).

Do you use either the Docs to Markdown or Markdown Preview add-ons? Are there other collaborative Markdown apps and systems you use that work well? Let me know what your experience has been when collaborating with others on Markdown files. Share your thoughts either in the comments or on Twitter (@awolber). 

Google Weekly Newsletter

Learn how to get the most out of Google Docs, Google Cloud Platform, Google Apps, Chrome OS, and all the other Google products used in business environments.
Delivered Fridays

Sign up today

Also see