fix(docs): preserve block replacement structure (#842)

steipete · web-flow · commit c02fdf7bc1a1 · 2026-06-18T12:28:35.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@
 
 ### Fixed
 
+- Docs: preserve the matched paragraph's list or heading structure on the first plain paragraph of a block Markdown replacement. (#838) — thanks @sebsnyk.
 - Calendar: report multi-calendar event truncation on stderr for text output and as per-calendar page tokens in JSON. (#831) — thanks @TurboTheTurtle.
 - Downloads: protect Drive downloads, Docs/Sheets/Slides exports, Docs tab exports, and Slides thumbnails from replacing existing files unless `--overwrite` is passed. (#827, #829) — thanks @WadydX.
 - Docs: update the Docker authentication example to persist file-keyring tokens with `GOG_HOME`. (#828, #830) — thanks @WadydX.
diff --git a/internal/cmd/docs_find_replace_test.go b/internal/cmd/docs_find_replace_test.go
@@ -536,6 +536,75 @@ func TestDocsFindReplace_MarkdownResetsInheritedParagraphStyle(t *testing.T) {
 	}
 }
 
+func TestDocsFindReplace_MarkdownBlockPreservesFirstPlainParagraphStyle(t *testing.T) {
+	for _, tc := range []struct {
+		name           string
+		paragraphStyle map[string]any
+		bullet         map[string]any
+	}{
+		{
+			name: "heading",
+			paragraphStyle: map[string]any{
+				"namedStyleType": "HEADING_2",
+			},
+		},
+		{
+			name: "bullet",
+			paragraphStyle: map[string]any{
+				"namedStyleType": "NORMAL_TEXT",
+				"indentStart": map[string]any{
+					"magnitude": 18,
+					"unit":      "PT",
+				},
+			},
+			bullet: map[string]any{"listId": "list-1"},
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var got docs.BatchUpdateDocumentRequest
+			body := docBodyWithText("Section\n")
+			paragraph := body["body"].(map[string]any)["content"].([]any)[1].(map[string]any)["paragraph"].(map[string]any)
+			paragraph["paragraphStyle"] = tc.paragraphStyle
+			if tc.bullet != nil {
+				paragraph["bullet"] = tc.bullet
+			}
+
+			docSvc, cleanup := newDocsServiceForTest(t, func(w http.ResponseWriter, r *http.Request) {
+				w.Header().Set("Content-Type", "application/json")
+				switch {
+				case r.Method == http.MethodGet && strings.HasPrefix(r.URL.Path, "/v1/documents/"):
+					_ = json.NewEncoder(w).Encode(body)
+				case r.Method == http.MethodPost && strings.HasSuffix(r.URL.Path, ":batchUpdate"):
+					if err := json.NewDecoder(r.Body).Decode(&got); err != nil {
+						t.Fatalf("decode batchUpdate: %v", err)
+					}
+					_ = json.NewEncoder(w).Encode(map[string]any{"documentId": "doc1"})
+				default:
+					http.NotFound(w, r)
+				}
+			})
+			defer cleanup()
+
+			err := runKong(t, &DocsFindReplaceCmd{}, []string{
+				"doc1", "Section", "First paragraph\n\nSecond paragraph", "--format", "markdown", "--first",
+			}, newDocsFindReplaceTestContext(t, docSvc), &RootFlags{Account: "a@b.com"})
+			if err != nil {
+				t.Fatalf("docs find-replace --format markdown --first: %v", err)
+			}
+
+			firstParagraphEnd := int64(1 + utf16Len("First paragraph\n"))
+			for _, req := range got.Requests {
+				if req.DeleteParagraphBullets != nil && req.DeleteParagraphBullets.Range.StartIndex < firstParagraphEnd {
+					t.Fatalf("first paragraph bullet reset: %#v", req.DeleteParagraphBullets.Range)
+				}
+				if req.UpdateParagraphStyle != nil && req.UpdateParagraphStyle.Range.StartIndex < firstParagraphEnd {
+					t.Fatalf("first paragraph style reset: %#v", req.UpdateParagraphStyle)
+				}
+			}
+		})
+	}
+}
+
 func TestDocsFindReplace_MarkdownCodeBlockStartsFreshParagraphWhenInline(t *testing.T) {
 	var batchCalls []docs.BatchUpdateDocumentRequest
 	docSvc, cleanup := newDocsServiceForTest(t, func(w http.ResponseWriter, r *http.Request) {
diff --git a/internal/cmd/docs_mutation.go b/internal/cmd/docs_mutation.go
@@ -179,7 +179,10 @@ func replacePreparedDocsMarkdownRange(
 			if docRangeCoversParagraphText(doc, startIdx, endIdx, tabID) {
 				resetEnd++
 			}
-			requests = append(requests, resetDocsParagraphRequests(baseIndex, resetEnd, tabID)...)
+			resetStart := markdownParagraphResetStart(elements, textToInsert, baseIndex)
+			if resetStart < resetEnd {
+				requests = append(requests, resetDocsParagraphRequests(resetStart, resetEnd, tabID)...)
+			}
 		}
 		requests = append(requests, formattingRequests...)
 	}
@@ -230,6 +233,16 @@ func markdownRangeReplacementIsInline(markdown string, elements []docsmarkdown.M
 		elements[0].Type == docsmarkdown.MDParagraph
 }
 
+func markdownParagraphResetStart(elements []docsmarkdown.MarkdownElement, text string, baseIndex int64) int64 {
+	if len(elements) == 0 || elements[0].Type != docsmarkdown.MDParagraph {
+		return baseIndex
+	}
+	if newline := strings.IndexByte(text, '\n'); newline >= 0 {
+		return baseIndex + utf16Len(text[:newline+1])
+	}
+	return baseIndex + utf16Len(text)
+}
+
 func resetDocsParagraphRequests(startIdx, endIdx int64, tabID string) []*docs.Request {
 	rng := &docs.Range{StartIndex: startIdx, EndIndex: endIdx, TabId: tabID}
 	return []*docs.Request{
