feat(docs): add --content-format markdown to +write helper

[raajheshkannaa]

Summary

Adds --content-format markdown flag to the gws docs +write helper. When set, markdown input is parsed and converted to Google Docs API batchUpdate requests with proper formatting.

# Before (plain text only)
gws docs +write --document DOC_ID --text '# Heading'
# Result: literal "# Heading" in the doc

# After (rendered markdown)
gws docs +write --document DOC_ID --content-format markdown --text '# Heading'
# Result: "Heading" formatted as Heading 1

Supported markdown

• Headings (H1-H6) via updateParagraphStyle with namedStyleType
• Bold, italic via updateTextStyle
• Inline code and code blocks via monospace font (Courier New)
• Links via updateTextStyle with link.url
• Bullet lists via createParagraphBullets
• Numbered lists via createParagraphBullets

Implementation

• Uses pulldown-cmark (MIT, pure Rust, widely used) for markdown parsing
• Single-pass AST walk collects text + formatting metadata
• One insertText request (full concatenated text) followed by N formatting requests
• Character indices use UTF-16 code units (matching Google Docs API convention)
• --content-format uses value_parser to constrain to plaintext or markdown

Tests

13 unit tests in docs_markdown.rs + 2 integration tests in docs.rs. All 545 existing tests continue to pass.

Future work (not in this PR)

• Tables (InsertTableRequest)
• Images (InsertInlineImageRequest)
• Blockquotes (indentation)
• Strikethrough
• Nested list indentation levels

Fixes #380

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2af1ddf

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[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]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the gws docs +write command by introducing support for markdown-formatted input. Previously limited to plain text, users can now leverage a new --content-format markdown flag to automatically convert common markdown elements into rich text formatting within Google Docs, streamlining content creation and reducing the need for manual formatting or complex API calls.

Highlights

• Markdown Support: Introduced a new --content-format markdown flag to the gws docs +write helper, enabling markdown input for Google Docs.
• Rich Text Conversion: Implemented conversion of various markdown syntaxes (headings, bold, italic, inline code, code blocks, links, and lists) into corresponding Google Docs API batchUpdate requests for proper formatting.
• Markdown Parser: Utilized the pulldown-cmark Rust crate for robust and efficient markdown parsing.
• API Compatibility: Ensured correct character index handling using UTF-16 code units to maintain compatibility with the Google Docs API.
• Testing: Added comprehensive unit tests for the new markdown conversion logic and updated integration tests for the +write helper, with all existing tests continuing to pass.

Changelog

• Cargo.lock
  • Updated to include new dependencies getopts, pulldown-cmark, pulldown-cmark-escape, and unicase required for markdown parsing.
• Cargo.toml
  • Added pulldown-cmark as a new project dependency.
• src/helpers/docs.rs
  • Modified the +write subcommand to accept a --content-format argument.
  • Updated help messages and examples to reflect markdown support.
  • Integrated the new markdown conversion logic when content-format is set to markdown.
  • Updated test utilities and added a new test case for markdown input.
• src/helpers/docs_markdown.rs
  • Added a new module containing the core logic for parsing markdown and generating Google Docs API batchUpdate requests.
  • Included extensive unit tests for the markdown conversion functionality.
• src/helpers/mod.rs
  • Exported the newly created docs_markdown module.

Activity

• A new feature was implemented to add markdown support to the gws docs +write helper.
• The pull request addresses and fixes issue feat: Support markdown formatting in docs +write helper #380.
• Thirteen new unit tests were added in docs_markdown.rs to validate the markdown conversion logic.
• Two integration tests in docs.rs were updated to cover the new markdown functionality.
• All 545 existing tests continue to pass, ensuring no regressions.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature for writing markdown content to Google Docs. The implementation is robust, leveraging pulldown-cmark for parsing and correctly handling UTF-16 indices for the Google Docs API. The new code is well-structured and includes a comprehensive set of unit tests for the markdown conversion logic. One point of feedback: the documentation file skills/gws-docs-write/SKILL.md was not updated to include the new --content-format flag. Please update this file to reflect the changes and new examples.

[jpoehnelt]

I'm not sure if this is the best path for this tool to include at this time. I'm concerned about this translation layer and the various edge cases.

[jpoehnelt]

Thanks for the contribution and the effort here! After thinking on it, I'm going to close this for now. The gws CLI is designed to be a thin transport layer over the Google APIs, and adding a markdown→Docs API translation layer introduces a lot of edge-case complexity that I don't think fits that philosophy.

[codecov]

Codecov Report

❌ Patch coverage is 93.68231% with 35 lines in your changes missing coverage. Please review.
✅ Project coverage is 64.30%. Comparing base (58c412c) to head (2af1ddf).
⚠️ Report is 7 commits behind head on main.

Files with missing lines	Patch %	Lines
src/helpers/docs_markdown.rs	94.72%	27 Missing ⚠️
src/helpers/docs.rs	80.95%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #383      +/-   ##
==========================================
+ Coverage   63.23%   64.30%   +1.07%     
==========================================
  Files          38       39       +1     
  Lines       15102    15651     +549     
==========================================
+ Hits         9549    10064     +515     
- Misses       5553     5587      +34     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.