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

gdoc-upsert

Creates or updates Google Docs from md-to-gdoc plans via the gws CLI.

Updated Sep 1, 2026
Search Tags:#markdown#publishing#google docs#batchupdate#gws cli#document sync#pageless layout
One-click install
npx skills add https://github.com/kevinhwang/.agents --skill gdoc-upsert-kevinhwang
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: gdoc-upsert
Source: https://github.com/kevinhwang/.agents/tree/main/skills/gdoc-upsert
Command: npx skills add https://github.com/kevinhwang/.agents --skill gdoc-upsert-kevinhwang

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Publishing Markdown content to Google Docs often breaks formatting: tables become pipe text, links die, and pageless layouts silently revert to paged when using Drive HTML media-upload. This Skill executes a prepared conversion plan against the Google Docs API so documents keep their native structure and layout. ## Core Features & Use Cases - Create mode: Builds a new Google Doc with a title, sets it to pageless (wide) layout, optionally places it in a Drive folder, then fills it with styled content. - Update mode: Replaces an existing doc's body in place via documents.batchUpdate while preserving its current layout (pageless or paged) and title. - Native structure: Inserts real tables, styled headings, live links, shaded code blocks, and native lists; images use ASCII fallback by default or temporary public Drive staging for raster insertion. - Use Case: After converting a Markdown report into a plan with md-to-gdoc, run this Skill to sync the latest version into an existing Google Doc without disturbing its pageless layout, then verify the round-trip with heading, table, and image counts. ## Quick Start Ask the agent to publish your Markdown report to a Google Doc by first generating a plan with md-to-gdoc and then running gdoc-upsert in create or update mode with the --go flag.

Frequently Asked Questions about gdoc-upsert

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

FAQPage Schema
How do I update a Google Doc from Markdown without breaking its layout?▼

Generate a plan with the md-to-gdoc skill, then run upsert.py in update mode with the doc ID and --go flag. It replaces the body via documents.batchUpdate, which leaves documentStyle untouched, so pageless or paged layout is preserved.

How do I create a pageless Google Doc from a Markdown file?▼

Convert the Markdown to a plan with md-to-gdoc, then run upsert.py create with a title and the plan path. The script creates the doc, sets documentFormat.documentMode to PAGELESS via updateDocumentStyle, and fills the content.

Why does my Google Doc lose its pageless layout after an update?▼

Drive HTML media-upload silently flips documentMode from PAGELESS to PAGES during HTML-to-Doc conversion. This Skill avoids that by using in-place batchUpdate body edits, which never touch documentStyle.

Can the Google Docs API insert local images into a document?▼

No, insertInlineImage requires a public URI for PNG, JPEG, or GIF and cannot use local files or base64 data. This Skill defaults to ASCII fallback text, or optionally stages images temporarily on Drive with public reader access when explicitly allowed.

Does the Google Docs API support native code blocks?▼

No, the API cannot create the native code-block widget and does not expose it on read. The Skill renders code as paragraphs with grey background shading and monospace font instead.

What dependencies does the gdoc-upsert script require?▼

It needs only Python 3 standard library and the authenticated gws CLI for Google Docs and Drive. There are no third-party Python packages, and it consumes a finished plan without importing the Markdown converter.

Related Skills

Explore More Content & Communication Skills→
TeiNamTeiNam
12

docx-generation

Generate Word .docx documents from text or Markdown content.

Community
Intermediate
cellarwoodcellarwood

recipe-organize-drive-folder

Organizes Google Drive folders and moves files into a project-based structure.

Official
Intermediate
sparklingsparkling
1

mermaid-export

Export Mermaid diagram blocks from Markdown, HTML, MDX, reStructuredText, and AsciiDoc documents to PNG images.

Community
Advanced
v1-iov1-io
6

md2docs

Convert Markdown files to Google Docs via the Google Drive API.

Official
Intermediate