fix(docs): preserve markdown paragraph breaks in tabs

CHANGELOG.md

@@ -8,6 +8,7 @@
 - Gmail: clarify that `gmail drafts delete` permanently deletes drafts and cannot be recovered. (#656, #659) — thanks @chrischall.
 - Sheets: add `--inherit-from-before` to `sheets insert` so callers can choose whether inserted rows/columns inherit formatting from the preceding or following neighbor. (#655, #658) — thanks @chrischall.
 - Auth: update stored OAuth scope metadata from observed granted scopes during refresh so `auth list` reflects newly usable services. (#649)
+- Docs: preserve paragraph-separating blank lines when replacing a single tab from Markdown. (#644)
 - Docs: update the bundled `gog` agent skill to preserve broad user OAuth scopes during reauth and rely on command guards for scoped execution.
 
 ## 0.19.0 - 2026-05-22

internal/cmd/docs_markdown.go

@@ -106,6 +106,9 @@ func ParseMarkdown(text string) []MarkdownElement {
 
 		// Empty line
 		if strings.TrimSpace(line) == "" {
+			if len(elements) > 0 && elements[len(elements)-1].Type != MDEmptyLine {
+				elements = append(elements, MarkdownElement{Type: MDEmptyLine})
+			}
 			continue
 		}
 
@@ -205,6 +208,10 @@ func ParseMarkdown(text string) []MarkdownElement {
 		})
 	}
 
+	if len(elements) > 0 && elements[len(elements)-1].Type == MDEmptyLine {
+		elements = elements[:len(elements)-1]
+	}
+
 	return elements
 }
 

internal/cmd/docs_markdown_test.go

@@ -46,7 +46,12 @@ func TestParseMarkdown(t *testing.T) {
 		{
 			name:     "mixed content",
 			input:    "# Title\n\nParagraph here\n\n- List item",
-			expected: []MarkdownElementType{MDHeading1, MDParagraph, MDListItem},
+			expected: []MarkdownElementType{MDHeading1, MDEmptyLine, MDParagraph, MDEmptyLine, MDListItem},
+		},
+		{
+			name:     "consecutive blank lines collapse",
+			input:    "Paragraph A\n\n\nParagraph B\n",
+			expected: []MarkdownElementType{MDParagraph, MDEmptyLine, MDParagraph},
 		},
 	}
 

internal/cmd/docs_write_markdown_tab_test.go

@@ -101,8 +101,8 @@ func TestDocsWrite_MarkdownReplaceWithTab(t *testing.T) {
 	if loc.TabId != "t.second" || loc.Index != 1 {
 		t.Fatalf("insert location = %+v, want {TabId:t.second Index:1}", loc)
 	}
-	if got := insertReqs[0].InsertText.Text; got != "Title\nbold\n" {
-		t.Fatalf("inserted text = %q, want %q", got, "Title\nbold\n")
+	if got := insertReqs[0].InsertText.Text; got != "Title\n\nbold\n" {
+		t.Fatalf("inserted text = %q, want %q", got, "Title\n\nbold\n")
 	}
 	for i, req := range insertReqs[1:] {
 		var r *docs.Range

internal/cmd/docs_write_markdown_test.go

@@ -500,7 +500,7 @@ func TestDocsWrite_MarkdownAppendUsesDocsFormatting(t *testing.T) {
 	if reqs[0].InsertText == nil {
 		t.Fatalf("expected first request to insert text, got %#v", reqs[0])
 	}
-	if got := reqs[0].InsertText; got.Location.Index != 9 || got.Text != "\nTitle\nbold\n" {
+	if got := reqs[0].InsertText; got.Location.Index != 9 || got.Text != "\nTitle\n\nbold\n" {
 		t.Fatalf("unexpected markdown insert: %#v", got)
 	}
 	if reqs[1].UpdateParagraphStyle == nil {
@@ -512,7 +512,7 @@ func TestDocsWrite_MarkdownAppendUsesDocsFormatting(t *testing.T) {
 	if reqs[2].UpdateTextStyle == nil {
 		t.Fatalf("expected bold text style request, got %#v", reqs[2])
 	}
-	if got := reqs[2].UpdateTextStyle.Range; got.StartIndex != 16 || got.EndIndex != 20 {
+	if got := reqs[2].UpdateTextStyle.Range; got.StartIndex != 17 || got.EndIndex != 21 {
 		t.Fatalf("unexpected bold range: %#v", got)
 	}
 }
@@ -569,13 +569,13 @@ func TestDocsWrite_MarkdownAppendStartsStyledBlocksOnFreshParagraph(t *testing.T
 	if len(reqs) != 4 {
 		t.Fatalf("expected insert, bullet, code font, and code shading requests, got %#v", reqs)
 	}
-	if got := reqs[0].InsertText; got == nil || got.Location.Index != 9 || got.Text != "\nItem\nline 1"+docsSoftLineBreak+"line 2\n" {
+	if got := reqs[0].InsertText; got == nil || got.Location.Index != 9 || got.Text != "\nItem\n\nline 1"+docsSoftLineBreak+"line 2\n" {
 		t.Fatalf("unexpected markdown insert: %#v", got)
 	}
 	if got := reqs[1].CreateParagraphBullets; got == nil || got.Range.StartIndex != 10 || got.Range.EndIndex != 15 {
 		t.Fatalf("unexpected bullet request: %#v", got)
 	}
-	if got := reqs[3].UpdateParagraphStyle; got == nil || got.Range.StartIndex != 15 || got.Range.EndIndex != 29 {
+	if got := reqs[3].UpdateParagraphStyle; got == nil || got.Range.StartIndex != 16 || got.Range.EndIndex != 30 {
 		t.Fatalf("unexpected code shading request: %#v", got)
 	}
 }