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
CODEBLOCK0
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. - Markdown must have proper
# headings. If the source has "heading-looking" plain text without # markers, add them before conversion. The script warns but proceeds. - Two-step process: create empty doc → populate with
update. This is deterministic and reliable. - Always verify heading syntax in the markdown before running. No
# = no formatted headings in the output.
What Works
- -
#–###### headings → Google Docs Heading 1–6 - INLINECODE13 → 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 → 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 .
- **Empty doc created**: The update` step failed. Check gog output for API errors.
Markdown 转 Google 文档
将 .md 文件转换为具有正确标题样式、粗体、代码块、列表、链接和引用块的 Google 文档。
环境要求
- - gog — Google Workspace 命令行工具（需完成身份验证：gog auth add <邮箱>）
- python3 — 用于脚本中的 JSON 解析
快速开始
bash
scripts/md-to-gdoc.sh <文件.md> [--title 标题] [--parent <文件夹ID>] [--account <邮箱>]
scripts/ 路径相对于本技能目录。
关键规则
- 1. 使用 gog docs update --format=markdown — 切勿使用 write --markdown 或 create --file。只有 update 路径能通过 API 正确应用 Google 文档的标题样式。
- Markdown 必须包含正确的 # 标题标记。 如果源文件中存在类似标题的纯文本但缺少 # 标记，请在转换前添加。脚本会发出警告但继续执行。
- 两步流程：创建空白文档 → 通过 update 填充内容。此方法确定性强且可靠。
- 运行前务必检查 Markdown 中的标题语法。缺少 # 标记 = 输出中无格式化标题。
支持的功能
- - #–###### 标题 → Google 文档标题 1–6
- 粗体 → 粗体文本
- 行内代码 → Courier New 字体
- 围栏代码块 → Courier New 字体 + 灰色背景
- > 引用块 → 缩进段落
- - 项目符号 → 带项目符号前缀的文本
- 1. 编号列表 → 带数字前缀的文本
- 文本 → 超链接
- Markdown 表格 → 原生 Google 文档表格
已知限制
- - 斜体 可能无法渲染（gog 命令行工具的行内格式解析器存在缺陷，某些情况下斜体检测失败）
- 项目符号/编号列表使用文本前缀（•、1.），而非原生 Google 文档列表对象
- 水平线渲染为 40 个短横线
可选参数
- - --title — 文档标题。默认使用文件名（连字符替换为空格）。
- --parent — 放置文档的 Google Drive 文件夹 ID。
- --account — Google 账户邮箱。默认使用 gog 的默认账户（首个通过身份验证的账户）。
故障排除
- - 所有内容均为正文文本，无标题：Markdown 文件缺少 # 标题标记。请添加。
- gog 身份验证错误：运行 gog auth list 检查验证状态。可能需要执行 gog auth add <邮箱>。
- 创建了空白文档：update 步骤失败。检查 gog 输出中的 API 错误信息。
