By name: gdocs-branded description: | Generate branded Google Docs from Markdown with full formatting. Only use when the user explicitly asks to create a branded Google Doc, generate a Google Doc with branding, or says "branded gdoc".
Branded Google Docs
Convert Markdown files into fully branded Google Docs with proper typography, colours, tables, and stable URLs.
Prerequisites
First-time setup (one-time only):
python3 ~/.config/google-docs/gdocs_auth.py
This opens a browser to authorise Google Docs and Drive access. See SETUP.md for full instructions.
Usage
python3 ~/.config/google-docs/gdocs_branded.py <markdown_file> --brand <name> [--doc-id-file gdocs_id.json] [--title "Title"]
Arguments
| Argument | Required | Description |
|---|---|---|
markdown_file |
Yes | Path to the Markdown source file |
--brand |
Yes | Brand name (built-in or custom) |
--doc-id-file |
No | JSON file to store/retrieve the Doc ID for stable URLs |
--title |
No | Document title (used on first create only) |
--folder-id |
No | Google Drive folder ID to create the doc in |
Built-in Brands
Three example brand configurations ship with the skill. Each demonstrates a different typographic strategy. Treat them as starting points — override via ~/.config/google-docs/brands.json to match your own brand system.
| Brand | Headings | Body | Palette |
|---|---|---|---|
editorial |
Libre Baskerville (serif) | Lato 11pt | Forest green + muted gold (classic book/magazine) |
corporate |
IBM Plex Sans (bold) | IBM Plex Sans 11pt | Slate blue accent on cool grey (clean business) |
modern |
Inter (geometric) | Inter 11pt | Electric teal + coral on near-black (contemporary tech) |
All three built-in brands use Google Fonts, which Google Docs renders natively. No embedding or font installation required.
Custom Brands
Create ~/.config/google-docs/brands.json to add your own brands or override the defaults. See SETUP.md for the JSON schema. Custom brands can use any Google Font.
Examples
Create a new branded document
python3 ~/.config/google-docs/gdocs_branded.py \
report.md \
--brand editorial \
--doc-id-file report_id.json \
--title "Q4 Strategy Report"
Update the same document (stable URL)
python3 ~/.config/google-docs/gdocs_branded.py \
report.md \
--brand editorial \
--doc-id-file report_id.json
The --doc-id-file stores the Google Doc ID on first run. Subsequent runs update the same document at the same URL.
How It Works
- Copies a brand-specific Google Docs template (preserving headers, footers, margins)
- Clears the body content
- Forces PAGES mode (prevents tables from overflowing page width)
- Parses Markdown into structured blocks (headings, paragraphs, bullets, numbered lists, tables)
- Inserts content via Google Docs API with inline brand-specific formatting
- Styles tables with brand colours (header row background, text colours, fonts)
Supported Markdown
- Headings (H1-H6)
- Bold, italic, bold+italic
- Bullet lists (two nesting levels)
- Numbered lists (two nesting levels)
- Pipe-separated tables with header rows
- Page breaks (
===on its own line)
Known Limitations
- No images (Google Docs API can insert images but not from local paths)
- No code blocks (rendered as plain paragraphs)
- Table cells lose inline bold/italic markers (stripped to plain text)
- Horizontal rules (
---) are skipped (use headings to separate sections)
Troubleshooting
"No token found" — Run python3 ~/.config/google-docs/gdocs_auth.py to authenticate.
"No template configured" — Add the brand to ~/.config/google-docs/templates.json with the template Google Doc ID.
"Unknown brand" — Check available brands with --brand nonexistent (error message lists all available brands).
Tables too wide — The script forces PAGES mode automatically. If tables still overflow, reduce column count or content length.
Numbered lists restart at 1 — Ensure numbered items are contiguous in the Markdown (no blank lines between items).