feat: Support markdown formatting in docs +write helper

[dd-rK]

Summary

The gws docs +write helper currently inserts plain text only. When writing markdown content to a Google Doc, all formatting (headings, bold, italic, code blocks, lists, tables) is lost — the raw markdown syntax appears as literal text.

Use Case

AI agents and CLI users frequently generate markdown content (RFCs, design docs, meeting notes) and need to push it to Google Docs with proper formatting. Currently, the only workaround is to create an empty doc via the API and manually paste markdown through the browser (right-click → paste from markdown). This breaks automation workflows.

Proposed Solution

Add a --content-format flag to +write (and potentially a new +write-md helper):

# Current (plain text only)
gws docs +write --document DOC_ID --text '# Heading\n\n**Bold text**'

# Proposed (markdown rendered)
gws docs +write --document DOC_ID --text '# Heading\n\n**Bold text**' --content-format markdown

Implementation approach

1. Add pulldown-cmark crate for markdown parsing
2. Parse markdown input into an AST
3. Convert AST nodes into Google Docs API batchUpdate requests:
   • # → updateParagraphStyle with namedStyleType: "HEADING_1"
   • **text** → updateTextStyle with bold: true
   • *text* → updateTextStyle with italic: true
   • `code` → updateTextStyle with font family monospace
   • - item → createParagraphBullets
   • Code blocks → monospace font + background color
4. Track 1-based character indices for all formatting ranges
5. Emit all requests in a single batchUpdate call

MVP scope (v1)

• Headings (H1-H6)
• Bold, italic, inline code
• Unordered and ordered lists
• Code blocks (monospace)
• Links

Future scope

• Tables
• Images (inline via insertInlineImage)
• Nested lists
• Horizontal rules

Relevant Code

The current +write implementation is in src/helpers/docs.rs, specifically the build_write_request() function which constructs a single insertText request. The change would extend this function (or add a parallel path) to generate formatting requests alongside text insertion.

Alternatives Considered

• Google Docs native markdown paste: Works in the browser UI but not via API
• Drive API import with conversion: Uploads files but doesn't reliably convert markdown formatting
• Apps Script: Works but requires additional setup and is not CLI-native

Context

This was discovered while building HIPAA-compliant architecture docs that needed to be shared via Google Docs. The inability to programmatically create formatted Google Docs from markdown is a gap in the CLI that affects both human users and AI agent workflows.

[dd-rK]

Simpler approach discovered: Drive API native markdown upload

The Google Drive API natively supports markdown → Google Docs conversion since July 2024. The upload just needs the right content types:

POST /upload/drive/v3/files?uploadType=multipart

Metadata: { "name": "My Doc", "mimeType": "application/vnd.google-apps.document" }
Body Content-Type: text/markdown
Body: <raw markdown content>

The current gws drive files create --upload file.md sends the file as application/octet-stream, which prevents conversion. The fix is:

1. Auto-detect .md files and set upload Content-Type to text/markdown
2. Set metadata mimeType to application/vnd.google-apps.document for conversion
3. OR add an --upload-content-type flag to let users specify the source MIME type

This handles headings, bold, italic, lists, tables, links — all rendered by Google's own converter. No need to build a markdown parser in Rust.

For the +write (append to existing doc) case, the batchUpdate approach is still needed since Drive API upload only creates new docs. But for the most common case (create a new formatted doc from markdown), Drive API upload is the 80% solution with 5% of the effort.

Proposed implementation

Phase 1 (MVP): Fix gws drive files create --upload to auto-detect markdown and convert
Phase 2 (future): Add gws docs +write --content-format markdown using batchUpdate for appending to existing docs

Will submit a PR for Phase 1.

[jpoehnelt]

The simpler approach with Drive is correct.

[peterHoburg]

The auto-detect of .md would be awesome. It would solve a lot of the issues I am seeing with formatting docs.

The "workaround" for updating an existing file would be to pull it down -> edit it -> re-upload as markdown. I don't love that workflow, but it would work for a 80/20 solution.