// The guide

Google Docs ↔ Markdown: a real round-trip with rclone.

2026-07-16 · 5 min read · by Nabil BA-MOH

Your collaborators live in Google Docs. Your tools — git, editors, AI assistants — live in markdown. The usual answer is to pick a side and suffer. You don't have to: Google Drive exports Docs as native markdown, rclone drives it from the command line, and the round-trip back updates the same doc in place. Same id, same URL, same sharing.

Everything below was verified on rclone v1.74 in July 2026, including id-stability checks across repeated pushes.

Pulling a Doc as clean markdown

Google Drive can export a Doc as native markdown — not HTML you convert afterwards, actual markdown. With rclone, one flag turns it on:

rclone copy "remote:folder" ./local --drive-export-formats md

Headings, bold and italics come through clean. Your Doc lands on disk as a .md file your whole toolchain understands.

Pushing markdown back — to the SAME doc

The reverse direction is where it gets good. This creates a real Google Doc from a markdown file:

rclone copyto file.md "remote:folder/file.md" \
  --drive-import-formats md --drive-export-formats md

And here is the part we specifically verified: pushing again later updates the same document in place. Same doc id, same URL, same sharing settings. Your collaborators' link never breaks; their comments stay attached to a living document. We confirmed this with id-stability checks across repeated pushes, not by assuming.

The gotcha that blocks everyone

On the push, the import and export format flags must BOTH be set to md. Leave the export flag off and rclone refuses with:

can't convert .md to a document with a different export filetype (.docx)

The error reads like a conversion problem; it is actually a flag problem. Set both flags and it works. This one line is probably why you are reading this post, so there it is.

Four more traps, all real

1. The Drive desktop sync folder is useless for this. In the synced folder, Docs and Sheets appear as .gdoc and .gsheet files — they are pointer files with no content. You cannot read a Doc through the filesystem. Go through the API, which is exactly what rclone does.
2. Never open your local mirror's .md from the Drive web UI. If you use "open with Google Docs" on an uploaded .md, Drive creates a duplicate document instead of converting in place. Now you have two docs and a confused team. The push command above is the only safe write path.
3. Delta sync is free. Re-running the same rclone sync with nothing changed transfers 0 bytes and finishes in about 0.4 seconds. You can run this in a loop or a cron without thinking about quota.
4. Split read and write into separate remotes. Configure one remote with the drive.readonly scope for pulls and a second with the full drive scope for pushes. The write-capable channel then only exists in the few places that explicitly use it — a cheap, real reduction in blast radius.

One forward-looking note: rclone's shared default Google client_id is being retired during 2026. Create your own client_id in Google Cloud Console and put it in the remote config; future you will thank present you.

What this unlocks: deferred co-authoring

The pattern this enables is worth naming. Working documents stay in Google, where the collaborators, comments and sharing already are. Your tools — and your AI — work on the markdown mirror, with version control and diffs. When a revision is ready, an explicit push publishes it back to the same shared doc everyone already has open. Nobody changes their workflow but you.

New to working this way? Start with our non-developer guide to Claude Code.

FAQ

1. Create your own in Google Cloud Console and set it in your remote config.