google-docs

Files (16)

• ci.yml · .github/workflows/
• .gitignore
• LICENSE
• README.md
• SKILL.md
• sample_operations.md · examples/
• gemini-extension.json
• cli-patterns.md · references/
• docs_operations.md · references/
• formatting_guide.md · references/
• integration-patterns.md · references/
• large-document-patterns.md · references/
• troubleshooting.md · references/
• docs_manager.rb · scripts/
• drive_manager.rb · scripts/
• insert_markdown_to_doc.rb · scripts/

SKILL.md (first lines)

# Google Docs & Drive Management Skill

## Purpose

Manage Google Docs documents and Google Drive files with comprehensive operations:

**Google Docs:**
- Read document content and structure
- Insert and append text
- Find and replace text
- Basic text formatting (bold, italic, underline)
- Insert page breaks
- Create new documents
- Delete content ranges
- Get document structure (headings)
- Insert inline images from URLs

**Google Drive:**
- Upload files to Drive
- Download files from Drive
- Search and list files
- Share files with users or publicly
- Create folders
- Move, copy, and delete files
- Get file metadata

**Integration**: The drive_manager.rb script shares OAuth credentials with docs_manager.rb

**📚 Additional Resources**:
- See `references/large-document-patterns.md` for inserting large formatted markdown into existing/template docs
- See `references/integration-patterns.md` for complete workflow examples
- See `references/troubleshooting.md` for error handling, debugging, Ruby version, and token format issues
- See `references/cli-patterns.md` for CLI interface design rationale

## When to Use This Skill

Use this skill when:
- User requests to read or view a Google Doc
- User wants to create a new document
- User wants to edit document content
- User requests text formatting or modifications
- User asks about document structure or headings
- User wants to find and replace text
- User needs to insert a **large markdown file** into an existing/template Google Doc
- User wants to insert **local images** into a Google Doc (via Drive upload)
- Keywords: "Google Doc", "document", "edit doc", "format text", "insert text", "insert markdown"

**⚠️ Large Document Insertion**: For markdown files >5KB or documents with many tables, use `scripts/insert_markdown_to_doc.rb` instead of `docs_manager.rb insert-from-markdown`. It handles rate limiting, batching, real table insertion, and code font formatting. See `references/large-document-patterns.md`.

**📋 Discovering Your Documents**:
To list or search for documents, use drive_manager.rb:
```bash
# List recent documents
scripts/drive_manager.rb search \
  --query "mimeType='application/vnd.google-apps.document'" \
  --max-results 50

# Search by name
scripts/drive_manager.rb search \
  --query "name contains 'Report' and mimeType='application/vnd.google-apps.document'"
```

## Core Workflows

### 1. Read Document

**Read full document content**:
```bash
scripts/docs_manager.rb read <document_id>
```

**Get document structure (headings)**:
```bash
scripts/docs_manager.rb structure <document_id>
```

**Output**:
- Full text content with paragraphs
- Document metadata (title, revision ID)
- Heading structure with levels and positions

### 2. Create Documents

**Create new document (plain text)**:
```bash
echo '{
  "title": "Project Proposal",
  "content": "Initial plain text content..."
}' | scripts/docs_manager.rb create
```

**Create document from Markdown (RECOMMENDED)**:
```bash
echo '{
  "title": "Project Proposal",
  "markdown": "# Project Proposal\n\n## Overview\n\nThis is **bold** and *italic* text.\n\n- Bullet point 1\n- Bullet point 2\n\n| Column 1 | Column 2 |\n|----------|----------|\n| Data 1   | Data 2   |"
}' | scripts/docs_manager.rb create-from-markdown
```

**Supported Markdown Features**:
- Headings: `#`, `##`, `###`, `####` → Google Docs HEADING_1 through HEADING_4
- Bold: `**text**`
- Italic: `*text*`
- Code: `` `text` `` → Consolas font (docs_manager uses Courier New; insert_markdown_to_doc uses Consolas)
- Code blocks: ` ``` ` → Consolas font (only in `insert_markdown_to_doc.rb`)
- Bullet lists: `- item` or `* item`
- Numbered lists: `1. item`
- Checkboxes: `- [ ] unchecked` and `- [x] checked`
- Horizontal rules: `---`
- Tables: `| col1 | col2 |` (with separator row, bold header in `insert_markdown_to_doc.rb`)
- Images: `![alt](path)` → uploaded to Drive and inserted inline (only in `insert_markdown_to_doc.rb` with `--insert-images`)

**Document ID**:
- Returned in response for future operations
- Use with drive_manager.rb for sharing/organizing

### 3. Insert and Append Text

**Insert plain text at specific position**:

From danielkwapien/google-docs-skill, MIT.