skills.rest
kevinhwang
kevinhwangCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

md-to-gdoc

Convert Markdown files into Google Docs batchUpdate JSON plans offline.

Updated Sep 1, 2026
Search Tags:#documentation#markdown#conversion#google docs#batchupdate#marko#code links
One-click install
npx skills add https://github.com/kevinhwang/.agents --skill md-to-gdoc-kevinhwang
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: md-to-gdoc
Source: https://github.com/kevinhwang/.agents/tree/main/skills/md-to-gdoc
Command: npx skills add https://github.com/kevinhwang/.agents --skill md-to-gdoc-kevinhwang

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires marko.

What problem does it solve? Turning a Markdown report into a properly structured Google Doc normally means manual copy-paste that loses headings, tables, links, and code formatting. This Skill parses Markdown into a JSON plan of Google Docs batchUpdate requests, preserving native structure without touching the network. ## Core Features & Use Cases - Full Markdown conversion: Parses CommonMark and GFM via marko into a plan covering headings, native lists, tables, fenced code blocks, inline code chips, links, and standalone images. - Repo-relative code link expansion: The coderef.py preprocessor rewrites repo-relative link hrefs into Sourcegraph or GitHub URLs based on the target org. - Image handling: Rasterizes local SVGs to PNG, references PNG/JPEG/GIF directly, and supports ASCII fallback text for environments without public image staging. - Use Case: You wrote an engineering design doc in Markdown with code references and a diagram. Run coderef.py then convert.py to produce plan.json, then hand it to the gdoc-upsert skill to create the real Google Doc. ## Quick Start Convert my Markdown report into a Google Docs plan and then create the actual Google Doc from it.

Frequently Asked Questions about md-to-gdoc

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I convert Markdown to a Google Doc with real formatting?▼

Run convert.py under uv run --with marko to produce a plan.json describing batchUpdate requests, then execute it with the gdoc-upsert skill's upsert.py to create or update the Doc. Headings, tables, lists, links, and code blocks are preserved as native Docs structures.

What Markdown features are supported when converting to Google Docs?▼

The converter uses marko with the GFM extension, so ATX headings, paragraphs, ordered and unordered lists, fenced and indented code, thematic breaks, GFM tables, standalone images, and inline bold, italic, code, and links all parse to spec, including nested emphasis.

Does the Markdown to Google Docs conversion need network access?▼

No, the conversion step is pure and offline; it only produces a JSON plan file. Network access is needed later by the companion gdoc-upsert skill, which executes the plan against the Google Docs API.

Can I convert Mermaid diagrams in Markdown to Google Docs?▼

The converter does not render Mermaid fenced blocks directly. Extract the block to a .mmd file, render it with Mermaid CLI (mmdc) to PNG, and embed the PNG as a standalone image, optionally with an ASCII fallback directive.

Why do Google Docs code blocks render as grey shaded paragraphs?▼

The Google Docs API cannot create the native code-block widget, so fenced code blocks become monospace paragraphs with grey paragraph shading as the faithful API-achievable equivalent. Whitespace and alignment are preserved exactly.

How do I link repo-relative code paths in Markdown to Sourcegraph or GitHub?▼

Run coderef.py as a preprocessor: it rewrites links whose href is a repo-relative path into full URLs, routing dropbox-internal org repos to Dropbox Sourcegraph and other orgs to GitHub, inferring blob versus tree from the path.

Related Skills

Explore More Content & Communication Skills→
Ameng2001Ameng2001
1

export-document

Export Markdown documents to DOCX and PDF with Mermaid diagrams and Chinese government formatting.

Community
Advanced
nomad3nomad3

gws-docs

Read, update, and create Google Docs via CLI with gws binary.

Community
Intermediate
kittnekittne

markdown

Enforce consistent Markdown formatting and structure across documentation.

Community
Intermediate
73ai73ai
4

recipe-generate-report-from-sheet

Extract Google Sheets data and generate formatted Google Docs reports.

Official
Intermediate