feat(docs): add docs.appendMarkdown for formatted writes without index math

[matheusrmorgado]

Summary

Fixes #400. Adds docs.appendMarkdown(documentId, markdown, tabId?): converts markdown into natively formatted Docs content in a single call.

docs.appendMarkdown({
  documentId: "...",
  markdown: "# Status\n\nShipping **on time**.\n\n- item one\n- item two"
})

Today the only way to produce formatted content is the two-step docs.writeText + docs.formatText flow, where the model hand-computes 1-based character indices (the google-docs skill spends most of its length teaching that arithmetic). For agents, markdown is the native output format — this removes the index math entirely.

Design

• Pure parser module (utils/markdown.ts): blocks (headings 1-6, bullets, numbered, paragraphs, horizontal rules) with inline formats (**bold**, *italic*/_italic_, ~~strikethrough~~, `code`, [links](url)) recorded as character ranges over the stripped text. Single-pass, non-nesting semantics, documented in the module.
• Two batchUpdates total: one insertText with the full stripped text, then one batch of updateParagraphStyle / updateTextStyle / createParagraphBullets requests computed from parse offsets. Consecutive list items of the same kind merge into single bullet ranges.
• tabId optional with the same convention/discovery as docs.writeText (flattened tab walk incl. child tabs; clear Tab with ID x not found error).
• Graceful degradation, explicit in the tool description: horizontal rules are skipped (no Docs API request exists for them) and counted in the response; tables are not parsed and fall through as plain paragraphs.
• No new OAuth scopes (documents already covers it). Registered in the docs.write feature group.

docs.formatText remains the right tool for fine-grained edits to existing text; this covers the much more common "write new formatted content" path.

What's included

• utils/markdown.ts parser + DocsService.appendMarkdown following the existing service conventions (logging, isError shape, TABS_FIELD_MASK reuse)
• Tool registration with Zod schema
• 16 Jest tests: 11 parser tests (inline markers incl. unclosed/empty edge cases, links, heading levels, list items with leading whitespace, hr, pipe-row fall-through, mixed document) and 5 service tests (exact request shapes incl. computed ranges, tabId threading, tab-not-found, hr-only short-circuit, error path)
• docs/index.md entry

Verification

npm run test && npm run lint && npm run format:check && npx tsc --noEmit --project workspace-server

All passing: 30 suites, 635 tests (619 existing + 16 new), eslint/prettier/tsc clean.

Made with Cursor

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request introduces the docs.appendMarkdown tool, allowing users to append markdown-formatted content directly to a Google Doc as natively formatted text. It includes a custom markdown parser utility and corresponding unit tests. The review feedback highlights a bug where appending to a non-empty document merges the first markdown block with the existing text, suggesting prepending a newline when insertAt > 1 and updating the affected tests. Additionally, it is recommended to support __ for bold text formatting to better align with standard markdown conventions.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[bdoyle0182]

appendMarkdown as a dedicated individual tool seems odd. I would try to propose something more akin to formatting that is generic and markdown as a param to the tool is just one option for the model to format the input