convez.ai
SkillAutomaçãoIntermediário
sunfmin

MD to Google Docs Tab

sunfmin/md-to-gdoc-tab

Sincroniza Markdown para Google Docs com uma única operação idempotente

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-tab

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

MarkdownGoogle Doc result
# TitleTITLE-styled paragraph
## HeadingHEADING_1
### HeadingHEADING_2
Blank-line-separated textNORMAL_TEXT paragraph
- itemBullet 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 topStripped before parsing

Not yet supported: images, code blocks, links, inline **bold** / *italic*. PRs welcome.

How it works

One batchUpdate per sync, containing in order:

  1. deleteContentRange over the tab body (leaves only the residual trailing \n).
  2. insertText with the full rendered content. Sub-bullets are prefixed with \t characters — one per nesting level.
  3. deleteParagraphBullets over the body (defence-in-depth against inherited bullet attrs on the residual paragraph).
  4. updateParagraphStyle per heading/title paragraph.
  5. createParagraphBullets per contiguous bullet group. Leading \t characters drive the nesting level; the API consumes them while assigning nestingLevel.

Re-running with the same Markdown converges the tab to the same state.

Two Google Docs API quirks worth knowing

  1. createParagraphBullets resets indentStart. Passing indentStart before/after has no effect on nestingLevel — the only signal that survives is the count of leading tab characters in the inserted text. The API reads them, sets nestingLevel = tab_count, and strips them.
  2. createParagraphBullets's range.endIndex is inclusive at the upper boundary for NORMAL_TEXT paragraphs (headings get filtered). If you pass range.endIndex equal to the start of the next paragraph and that paragraph is normal text, it gets a bullet too. This script ends bullet ranges at last_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 \n from before the rewrite, which Docs doesn't let you delete). Cosmetic.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados