docs write --replace --markdown --tab: paragraph blank lines collapse into soft line breaks

[sebsnyk]

Summary

When using gog docs write --replace --markdown --tab=<title> to rewrite a Google Doc tab from a markdown file, paragraph-level blank lines in the source are collapsed into soft line breaks ( two-space hard-break form) inside a single paragraph, instead of producing separate paragraph elements. The same source markdown rendered through gog docs write --replace --markdown --pageless (whole-doc, no --tab) does preserve paragraph breaks correctly — so it appears to be a --tab path regression.

Verified on gogcli v0.19.0 (Homebrew).

Repro

/tmp/in.md:

## Section heading

Paragraph A.

Paragraph B.

Paragraph C.

DOC_ID=...   # any doc with a tab titled "Test"
gog docs write "$DOC_ID" --replace --markdown --tab "Test" --file /tmp/in.md
gog drive download "$DOC_ID" --format md --out /tmp/out.md
sed -n '/## Section/,$p' /tmp/out.md

Expected (paragraph breaks preserved)

## Section heading

Paragraph A.

Paragraph B.

Paragraph C.

Actual (paragraphs collapsed into soft line breaks)

## Section heading

Paragraph A.  
Paragraph B.  
Paragraph C.

The trailing two-space line-break in the round-trip export indicates the converter wrote these as a single Docs paragraph element with line breaks, not three separate paragraphs.

Comparison with whole-doc path

The same source markdown rendered via gog docs write --replace --markdown --pageless (no --tab flag) produces three separate paragraphs as expected. The behavioural delta is specific to the --tab path.

Impact

• Long-form status update tabs lose the visual structure they had when authored by hand.
• The first rewrite of any tab also re-flattens existing paragraphs that were authored manually, because the tab content is round-tripped through the converter.
• Doubling the blank lines in source (\n\n\n) does not help — it appears the converter normalises blank line count to a single break.

Workaround

Convert paragraphs to bullet list items. Bullet items render with proper list-item spacing in Google Docs, sidestepping the paragraph-flattening behaviour. Not a fix — bullets are the wrong markup for narrative status updates.

Notes

• + and & escape as \+ and \& in the round-trip, but that is cosmetic in the markdown export and renders correctly in the Doc UI.
• Heading-level blank lines (around ###) are preserved correctly; the issue is purely paragraph-to-paragraph inside a section.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed May 26, 2026, 9:50 AM ET / 13:50 UTC.

Summary
Keep open. Current main still uses the local Docs API markdown renderer for --replace --markdown --tab, and that path drops blank markdown lines before insertion, so the reported paragraph-break regression is not already fixed.

Reproducibility: Not from this review as a live Google Docs round trip. The reporter supplied exact v0.19.0 steps, and source inspection shows the tab path drops blank markdown lines before insertion.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
A focused repair PR is plausible in internal/cmd, but the final merge should require live Docs round-trip proof because the failure depends on Google API/export behavior.

Review details

Best possible solution:

Patch the tab-local markdown renderer to preserve paragraph boundaries consistently with whole-document Drive import, with focused regression coverage and live Google Docs round-trip proof.

Do we have a high-confidence way to reproduce the issue?

Not from this review as a live Google Docs round trip. The reporter supplied exact v0.19.0 steps, and source inspection shows the tab path drops blank markdown lines before insertion.

Is this the best way to solve the issue?

Yes. The narrow maintainable fix is in the existing local markdown tab renderer, not a new flag or product surface.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A code-only unit test may not prove the live Google Docs tab insertion/export semantics; a fix should include a redacted live round-trip proof before merge.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9987f8b2f053.

Label changes

Label changes:

• add P2: This is a normal-priority Docs markdown bug with a focused surface and limited blast radius.
• add impact:data-loss: The issue reports tab replacement corrupting authored document structure by flattening separate paragraphs into line breaks.
• add issue-rating: 🐚 platinum hermit: Current issue advisory state selects this label.
• add clawsweeper:needs-live-repro: Current issue advisory state selects this label.

Label justifications:

• P2: This is a normal-priority Docs markdown bug with a focused surface and limited blast radius.
• impact:data-loss: The issue reports tab replacement corrupting authored document structure by flattening separate paragraphs into line breaks.

Evidence reviewed

Acceptance criteria:

• go test ./internal/cmd -run 'TestDocsWrite_MarkdownReplaceWithTab|TestMarkdownToDocsRequests|TestParseMarkdown'
• make test
• Live validation: run the issue's gog docs write --replace --markdown --tab repro against a test Google Doc and confirm gog drive download --format md preserves blank lines between paragraphs.

What I checked:

• Tab replace uses local markdown insertion: replaceMarkdownInTab clears the selected tab and then calls insertDocsMarkdownAt, so this path bypasses Drive's whole-document markdown converter. (internal/cmd/docs_edit.go:482, 9987f8b2f053)
• Blank markdown lines are skipped: ParseMarkdown treats empty or whitespace-only markdown lines as continue, so paragraph-separating blank lines are not represented in the parsed element stream. (internal/cmd/docs_markdown.go:107, 9987f8b2f053)
• Paragraph renderer emits one newline per paragraph element: The formatter appends only the paragraph text plus a single newline for each MDParagraph; the MDEmptyLine case is unreachable for parsed blank source lines because the parser skips them. (internal/cmd/docs_formatter.go:252, 9987f8b2f053)
• Existing tab test expects collapsed blank-line output: The current tab replacement regression test feeds markdown with a blank line after a heading and expects inserted text Title\nbold\n, confirming current test coverage does not preserve the blank separator. (internal/cmd/docs_write_markdown_tab_test.go:104, 9987f8b2f053)
• No later docs-area fix on current main: The diff from the latest release commit to current main does not touch the Docs markdown/tab files, so the v0.19.0 behavior reported by the issue remains on main. (9987f8b2f053)
• Feature provenance: The whole-tab markdown render path shipped in v0.18.0 for the earlier tab replacement request, while the reporter verified this paragraph regression on v0.19.0. (CHANGELOG.md:42, 9987f8b2f053)

Likely related people:

• Peter Steinberger: Visible git blame, shortlog, and release history tie the current Docs markdown parser, formatter, tab replacement implementation, and tab tests to the v0.19.0 release commit. (role: recent area contributor; confidence: medium; commits: b25a3c029b37; files: internal/cmd/docs_edit.go, internal/cmd/docs_markdown.go, internal/cmd/docs_formatter.go)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.