MD to Google Docs Tab
sunfmin/md-to-gdoc-tab
Sincroniza Markdown para Google Docs com uma única operação idempotente
Ver no GitHubSkill que sincroniza um arquivo Markdown local para uma aba específica de um Google Doc de forma idempotente. Trata o arquivo .md como fonte de verdade e a aba como visualização renderizada, executando a operação em um único batchUpdate da API.
Instalação
npx convez-ai sunfmin/md-to-gdoc-tab1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter documentação em Google Docs sincronizada com repositório de código
- Automatizar atualização de especificações técnicas em abas de Google Docs
- Integrar pipeline de CI/CD para renderização de Markdown em Docs
Veredito

Solução pragmática que resolve um problema real da API do Google Docs — ausência de forma declarativa para sincronizar conteúdo em abas. Implementação limpa como Skill, com suporte a Markdown bastante funcional (headings, bullets aninhados, tabelas). Pronto para uso em automações documentadas.
README
A tradução para o português deste README ainda está na fila.
md-to-gdoc-tab
Idempotently sync a local Markdown file into a specific tab of a Google Doc, in one batchUpdate. Treats the .md file as source of truth and the tab as a rendered view.
Packaged as a Claude Code Agent Skill (SKILL.md) — but render.py is a standalone Python script and runs fine without Claude Code. Install it under ~/.claude/skills/md-to-gdoc-tab/ and Claude Code (or any compatible agent runtime) will pick it up automatically.
Why
Google Docs API is purely imperative — every edit is an index-based op (insertText, deleteContentRange, updateParagraphStyle, createParagraphBullets, …). There is no declarative endpoint that takes a desired body. Hand-driving the API is painful and easy to break. None of the existing wrappers (markgdoc, timwis/markdown-to-google-doc, pandoc, Drive API's server-side Markdown importer) understand the tabs feature or replace a tab in place idempotently.
This tool fills that gap.
Install
git clone https://github.com/sunfmin/md-to-gdoc-tab.git ~/.claude/skills/md-to-gdoc-tab
Or anywhere else if you don't use Claude Code — just adjust the path you call render.py with.
Prerequisites
You need gws (Google Workspace CLI), authenticated:
brew install googleworkspace-cli # or: npm i -g @googleworkspace/cli
gws auth login # interactive — opens browser
gws auth status | grep token_valid # must be true
Use
python3 ~/.claude/skills/md-to-gdoc-tab/render.py \
--md /path/to/source.md \
--doc-id <DOC_ID> \
--tab-id <TAB_ID>
Add --dry-run to print the generated batchUpdate request JSON without calling the API.
Finding the tab ID
Open the doc, click the tab you want, look at the URL — it ends in tab=t.XXXXXXX. That's the tabId.
Markdown subset supported
| Markdown | Google Doc result |
|---|---|
# Title | TITLE-styled paragraph |
## Heading | HEADING_1 |
### Heading | HEADING_2 |
| Blank-line-separated text | NORMAL_TEXT paragraph |
- item | Bullet at level 0 (•) |
- sub-item (4 spaces) | Bullet at level 1 (◦) |
- deeper (8 spaces) | Bullet at level 2 (■) |
--- (horizontal rule) | Skipped |
GFM table (| a | b |) | Real Google Docs table — bold header, fixed-width cols (last block only) |
| YAML frontmatter at top | Stripped before parsing |
Not yet supported: images, code blocks, links, inline **bold** / *italic*. PRs welcome.
How it works
One batchUpdate per sync, containing in order:
deleteContentRangeover the tab body (leaves only the residual trailing\n).insertTextwith the full rendered content. Sub-bullets are prefixed with\tcharacters — one per nesting level.deleteParagraphBulletsover the body (defence-in-depth against inherited bullet attrs on the residual paragraph).updateParagraphStyleper heading/title paragraph.createParagraphBulletsper contiguous bullet group. Leading\tcharacters drive the nesting level; the API consumes them while assigningnestingLevel.
Re-running with the same Markdown converges the tab to the same state.
Two Google Docs API quirks worth knowing
createParagraphBulletsresetsindentStart. PassingindentStartbefore/after has no effect onnestingLevel— the only signal that survives is the count of leading tab characters in the inserted text. The API reads them, setsnestingLevel = tab_count, and strips them.createParagraphBullets'srange.endIndexis inclusive at the upper boundary forNORMAL_TEXTparagraphs (headings get filtered). If you passrange.endIndexequal to the start of the next paragraph and that paragraph is normal text, it gets a bullet too. This script ends bullet ranges atlast_bullet_start + 1(one char inside the last bullet) to avoid the leak.
Limitations
- Replaces the entire target tab body — comments/suggestions on that tab are lost. (The rest of the doc, including other tabs, is untouched.)
- One tab per call. To sync multiple tabs, run multiple times.
- One trailing empty paragraph at the end of the rebuilt tab (the body's residual
\nfrom before the rewrite, which Docs doesn't let you delete). Cosmetic.
License
MIT. See LICENSE.