md-to-gdoc

name	md-to-gdoc
description	Convert markdown files to properly formatted Google Docs. Use when asked to create a Google Doc from markdown, upload markdown to Google Docs, put a .md file into Google Docs, or convert research/notes/documents to Google Docs format.

Markdown to Google Doc

Convert .md files into Google Docs with proper heading styles, bold, code blocks, lists, links, and blockquotes.

Requirements

• gog — Google Workspace CLI (must be authenticated: gog auth add <email>)
• python3 — used for JSON parsing in the script

Quick Start

scripts/md-to-gdoc.sh <file.md> [--title "Title"] [--parent <folder-id>] [--account <email>]

Resolve scripts/ relative to this skill's directory.

Critical Rules

1. Use gog docs update --format=markdown — never write --markdown, never create --file. The update path is the only one that correctly applies Google Docs heading styles via the API.
2. Markdown must have proper # headings. If the source has "heading-looking" plain text without # markers, add them before conversion. The script warns but proceeds.
3. Two-step process: create empty doc → populate with update. This is deterministic and reliable.
4. Always verify heading syntax in the markdown before running. No # = no formatted headings in the output.

What Works

• #–###### headings → Google Docs Heading 1–6
• **bold** → bold text
• `inline code` → Courier New
• Fenced code blocks → Courier New + gray background
• > blockquotes → indented paragraphs
• - bullets → bullet-prefixed text
• 1. numbered → number-prefixed text
• [text](url) → hyperlinks
• Markdown tables → native Google Docs tables

Known Limitations

• *italic* may not render (gog CLI bug in inline formatting parser — italic detection fails in certain contexts)
• Bullet/numbered lists use text prefixes (•, 1.), not native Google Docs list objects
• Horizontal rules render as 40 dashes

Options

• --title — Doc title. Defaults to filename with hyphens→spaces.
• --parent — Google Drive folder ID to place the doc in.
• --account — Google account email. Defaults to gog's default (first authenticated account).

Troubleshooting

• All body text, no headings: The markdown file lacks # heading markers. Add them.
• gog auth errors: Run gog auth list to verify auth. May need gog auth add <email>.
• Empty doc created: The update step failed. Check gog output for API errors.