Install the md2gd client

One dependency-free binary that watches your local Markdown and keeps it two-way synced with Google Docs. Pick your platform below.

verify downloads with checksums.txt
1

Install (one line)

Run this in Terminal. It downloads the right build, verifies its checksum, and installs it:

curl -fsSL https://md2gd.com/install.sh | sh
Set MD2GD_INSTALL_DIR to choose where it lands (default /usr/local/bin, falling back to ~/.local/bin).
2

Or download the binary directly

Apple Silicon (M1 and newer) uses arm64. Older Intel Macs use amd64.

Apple Silicon (arm64) Intel (amd64)
Then extract and put it on your PATH:
tar -xzf md2gd_darwin_arm64.tar.gz
sudo mv md2gd /usr/local/bin/
First run may hit Gatekeeper (unsigned): clear the quarantine flag with xattr -d com.apple.quarantine /usr/local/bin/md2gd.

Get started

Sign in once, then link a Markdown file to a Google Doc. Syncing starts automatically.

1

Sign in

Opens your browser to connect your Google account.

md2gd login
2

Link a file to a Doc

Create a new Google Doc for the file (or use --pick to choose an existing one in the browser). Syncing starts in the background and keeps both sides current, block by block.

md2gd add notes.md --create

Syncing runs as a background service that auto-starts on login. See the command reference for turning it on and off and everything else the client does.

Teach your AI agent recommended

If you draft these docs with an AI coding agent, add a short rule so it writes only the Markdown md2gd can sync, and never the images, task lists, or other constructs that would freeze the doc. Pick your agent, drop in the file, done.

1

Get the rule

Reads a CLAUDE.md at the root of your project (or repo).

2

Put it in place

Save it as CLAUDE.md in your project (the folder that holds your synced Markdown).

Already have a CLAUDE.md? Paste the rule into it instead of overwriting, since Claude reads the whole file.
Preview the rule
# Writing Markdown that syncs cleanly to Google Docs (md2gd)

Markdown files in this project may be kept in two-way sync with Google Docs by
md2gd, which supports only a closed set of Markdown features that round-trip
losslessly. If a file uses anything outside that set, md2gd **freezes that doc's
sync** rather than mangling it: the sync stops until the unsupported construct is
removed.

So whenever you write or edit Markdown here, use **only** the features under
"Allowed" and **never** the ones under "Freezes the sync".

## Allowed (always safe)
- Headings `#` through `######` (H1 to H6)
- Plain paragraphs
- **Bold** (`**bold**`) and *italic* (`*italic*`)
- Strikethrough: `~~text~~`
- Task lists: `- [ ] text` (unchecked) and `- [x] text` (checked)
- `Inline code` with backticks
- Inline links only: `[text](https://example.com)`
- Bulleted lists with `- ` (nest at most one level, 2-space indent)
- Numbered lists with `1. ` (nest at most one level)
- Fenced code blocks with triple backticks (a language tag is fine)
- Blockquotes with `> ` (single level only)
- GFM tables: a header row, a divider row (`| --- | --- |` or with alignment colons
  `:---`, `---:`, `:---:`), and body rows

## Freezes the sync (never use these)
- Images: `![alt](path)`
- Horizontal rules: `---`, `***`, `___`
- Footnotes: `[^1]`
- Reference-style links: `[text][ref]`
- List nesting deeper than one level, or mixing bullets and numbers when nested
- Nested blockquotes (`> >`)
- Headings deeper than H6
- Highlighted or colored text, raw HTML tags, embeds, page breaks

## Write it the canonical way
- Bold with `**`, italic with `*` (not `__` or `_`)
- Bullets with `- `; ordered lists with `1.`
- One nesting level = exactly two spaces
- One blank line between blocks; end the file with a single newline
- Links inline, never reference-style

If the content genuinely needs something outside the Allowed list, such as a real
table, an image, or a diagram, **tell the user instead of writing it**. Otherwise
that document will stop syncing.