Google Docs Markdown

Convert markdown to fully formatted Google Docs -- headings, lists, tables, code blocks, and more -- via the Google Docs and Drive APIs. Organize into folders, add logos, and share with recipients in a single operation.

When to Use

• Delivering professional documents to clients or collaborators via Google Drive
• Batch-uploading markdown files as formatted Google Docs
• Automating document workflows (draft in markdown, publish to Drive)
• Sharing branded documents with logos and organized folder structures
• Any time you need real Google Docs (not exported HTML or PDFs)

What It Does

This skill provides a Python library (gdocs.py) that:

1. Creates Google Docs from markdown with proper formatting (H1-H6, bullets, numbered lists, checkboxes, blockquotes, tables, code blocks, horizontal rules, bold)
2. Manages Drive folders -- creates, organizes, and shares them
3. Handles images -- uploads to Drive and embeds at the top of documents (logos, headers)
4. Shares with recipients -- writer or reader access, with notification emails
5. Batch uploads -- process an entire directory of .md files into a shared folder

Setup (One-Time)

1. Google Cloud Project

1. Go to Google Cloud Console
2. Create a new project (or use an existing one)
3. Enable these APIs:

- Google Docs API - Google Drive API

2. OAuth Credentials

1. Go to APIs & Services > Credentials
2. Click Create Credentials > OAuth 2.0 Client ID
3. Application type: Desktop app
4. Download the JSON file
5. Save it as google_credentials.json in the same directory as gdocs.py (or set a custom path)

3. Install Dependencies

pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

4. First Run

The first time you run the library, it opens a browser for Google authorization. After authorizing, a google_token.json file is saved locally for future runs (auto-refreshes).

Usage

Python API

from gdocs import GoogleDocsClient

client = GoogleDocsClient(
    credentials_file="path/to/google_credentials.json",  # optional, defaults to same dir
    token_file="path/to/google_token.json"                # optional, defaults to same dir
).authenticate()

# Create a single doc
doc_id, url = client.create_doc("My Document Title", markdown_text)
print(url)

# Create a doc in a folder
folder_id = client.create_folder("Project Documents")
doc_id, url = client.create_doc("Report", markdown_text, folder_id=folder_id)

# Share with someone
client.share(doc_id, "[email protected]", role="writer")

# Batch upload a folder of .md files
result = client.upload_markdown_folder(
    source_dir="./docs/",
    folder_name="Project Documents",
    share_with="[email protected]",
    share_role="writer",
    title_prefix="Project Name",     # optional: prepends to doc titles
    logo_path="./assets/logo.png",   # optional: inserts at top of each doc
)
print(result["folder_url"])
for title, url in result["docs"]:
    print(f"  {title}: {url}")

CLI

# Upload markdown files to a shared folder
python gdocs.py upload file1.md file2.md --folder "My Folder" --share [email protected]

# With logo and title prefix
python gdocs.py upload *.md --folder "Docs" --prefix "Project" --logo logo.png --share [email protected]

# Create a folder and share it
python gdocs.py folder "New Folder" --share [email protected]

# List recent docs
python gdocs.py list

Claude Code Integration

To use this as a Claude Code skill:

1. Copy gdocs.py to a stable location (e.g., ~/.local/lib/gdocs.py)
2. Place credentials alongside it or set custom paths
3. In Claude Code, import and use:

import sys, os
sys.path.insert(0, os.path.expanduser("~/.local/lib"))
from gdocs import GoogleDocsClient

client = GoogleDocsClient().authenticate()
doc_id, url = client.create_doc("Title", markdown_content)

API Reference

Markdown Features Supported

Troubleshooting

Anti-Patterns

• Don't use for real-time collaboration -- This creates documents, it doesn't sync them. For live editing, just use Google Docs directly.
• Don't hardcode credentials paths -- Use the constructor parameters or environment variables.
• Don't skip the empty-range filter -- The Google Docs API rejects updateTextStyle requests where startIndex >= endIndex. The library handles this automatically.
• Don't upload massive documents in one shot -- The batch update API has a practical limit. For very large documents (1000+ lines), consider splitting into multiple docs.

Origin

Extracted from a real project: building protocol documents for a multi-week creative gathering in Panama. Three 100+ line markdown documents needed to be delivered as professionally formatted Google Docs with logos, organized in folders, and shared with the event organizer. The initial approach (manual Google Docs creation) was replaced with this automated pipeline that handles the full workflow in seconds.

The library was first built as a one-off upload script, then generalized into a reusable tool after recognizing the pattern would recur across projects.

Part of Claude Code Skills -- reusable skills extracted from real AI-assisted development sessions.