Google Docs from Markdown

核心用法

gdocs-markdown 解决了 gog docs CLI 无法直接写入或更新 Google Docs 内容的痛点。该技能采用迂回策略：先将 Markdown 转换为 DOCX 格式，再通过 Google Drive 上传（Drive 会自动将 DOCX 转换为 Google Docs 格式）。主要入口是 gdocs-create.sh 脚本，支持一键完成整个流程，也允许用户分步手动执行以获得更精细的控制。

显著优点

• 填补 CLI 功能空白：绕过 gog docs 仅支持 create/export/cat/copy 的限制，实现内容填充
• 格式兼容性好：借助 pandoc 进行 Markdown→DOCX 转换，保留大部分排版格式
• 自动化程度高：单条命令即可完成从本地 Markdown 到云端 Google Docs 的完整链路
• pandoc 自托管：首次使用时自动下载 pandoc 二进制文件，降低环境配置门槛

潜在缺点与局限性

• 间接依赖风险：流程涉及 pandoc 下载、DOCX 中转、Drive 格式转换三个环节，任一环节失败都会导致整体失败
• 权限配置繁琐：安装后需手动执行 chmod +x 修复脚本权限，体验不够流畅
• 临时文件残留：转换过程中产生的 DOCX 文件默认保留在 Drive，需手动清理
• 格式转换损耗：复杂 Markdown 特性（如高级表格、数学公式）在 DOCX→Google Docs 二次转换中可能丢失
• 网络依赖重：pandoc 下载和 Drive 上传均需外网连接

适合人群

• 习惯用 Markdown 写作但需要最终交付 Google Docs 格式的用户
• 使用 gog CLI 进行 Google Workspace 自动化管理的开发者
• 团队协作中需要将版本控制的 Markdown 文档同步到 Google Drive 的场景

常规风险

• 凭证泄露：脚本运行依赖 gog CLI 的 Google 账号认证，共享环境需注意凭证隔离
• 临时文件安全：转换过程中的 DOCX 文件在 /tmp 和 Drive 中短暂存在，敏感文档需注意清理
• 第三方二进制：自动下载的 pandoc 来自外部源，企业环境建议预置可信版本替代自动下载

核心用法

gdocs-markdown 解决了一个具体的工具链缺口：gog docs CLI 仅支持创建空文档、导出、读取和复制，但不支持写入或更新内容。该 skill 通过 Markdown → DOCX → Google Drive 上传的间接路径，实现了「带内容创建 Google Docs」的能力。

典型工作流：
1. 用户准备 Markdown 文件（含标题、正文、格式标记）
2. 执行 gdocs-create.sh /path/to/file.md "文档标题"
3. 脚本自动下载/调用 pandoc 将 Markdown 转为 DOCX
4. 通过 gog drive upload 上传，Drive 自动转换为可编辑的 Google Docs 格式
5. 返回可直接编辑的文档链接

显著优点：

• 精准补位：填补了 gog CLI 的功能缺口，无需手动操作 Google Docs Web 界面
• 格式保留：pandoc 转换能较好地保留 Markdown 的标题层级、列表、粗体斜体等格式
• 自动化友好：命令行一键操作，适合 CI/CD 文档生成、报告自动化等场景
• 轻量无依赖：核心逻辑为 176 行 bash 脚本，无重型第三方库依赖

潜在缺点与局限性：

• 依赖外部工具链：必须预装 gog CLI 并完成 Google 账号授权，且需网络下载 pandoc
• 网络下载风险：首次运行自动从 GitHub 下载 pandoc 二进制（固定版本 3.1.11，来源可信但无本地哈希校验）
• 格式转换边界：复杂 Markdown（表格嵌套、LaTeX 公式、Mermaid 图表）可能转换不完美
• 权限摩擦：Linux/macOS 安装后需手动 chmod +x 修复脚本权限
• 无增量更新：每次调用创建新文档，不支持对已有文档的内容追加或修改

适合人群：

• 使用 gog CLI 管理 Google Workspace 的开发者/运维人员
• 需要将 Markdown 报告、文档自动发布到 Google Docs 的内容团队
• 构建文档自动化流水线（如每日/每周报告生成）的技术团队

常规风险：

• 供应链风险：动态下载 pandoc 虽来源可信，但建议添加 SHA256 校验
• 凭证暴露：依赖 gog CLI 的本地授权状态，需确保运行环境已安全配置
• 临时文件残留：/tmp 目录的 pandoc 和解压文件需关注磁盘清理