fix(docs): preserve revision for markdown inserts

steipete · steipete · commit f0a0acef796c · 2026-06-19T12:57:20.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@
 
 ### Added
 
-- Docs: add `insert --markdown` to convert markdown to Google Docs formatting and place the converted block at a position resolved by `--index`/`--at`/`--occurrence`, giving `insert` parity with the existing `update --markdown` and `write --markdown` paths. (#851)
+- Docs: add `insert --markdown` to convert markdown to Google Docs formatting and place the converted block at a position resolved by `--index`/`--at`/`--occurrence`, giving `insert` parity with the existing `update --markdown` and `write --markdown` paths. (#851, #854) — thanks @sebsnyk.
 
 ## 0.29.0 - 2026-06-19
 
diff --git a/internal/cmd/docs_edit.go b/internal/cmd/docs_edit.go
@@ -969,7 +969,7 @@ func (c *DocsInsertCmd) Run(ctx context.Context, kctx *kong.Context, flags *Root
 	c.Tab = resolvedPlacement.TabID
 
 	if c.Markdown {
-		return c.runMarkdown(ctx, svc, docID, insertIndex, content)
+		return c.runMarkdown(ctx, svc, docID, insertIndex, resolvedPlacement.RequiredRevisionID, content)
 	}
 
 	batchReq := &docs.BatchUpdateDocumentRequest{
@@ -1006,9 +1006,25 @@ func (c *DocsInsertCmd) Run(ctx context.Context, kctx *kong.Context, flags *Root
 // insertion helper that backs `docs write --markdown` and the non-replacing
 // branch of `docs update --markdown`, so headings, fenced code blocks, lists,
 // tables and images render identically regardless of which command placed them.
-func (c *DocsInsertCmd) runMarkdown(ctx context.Context, svc *docs.Service, docID string, insertIndex int64, content string) error {
+func (c *DocsInsertCmd) runMarkdown(
+	ctx context.Context,
+	svc *docs.Service,
+	docID string,
+	insertIndex int64,
+	requiredRevisionID string,
+	content string,
+) error {
 	markdown := prepareMarkdown(content)
-	insertResult, err := insertPreparedDocsMarkdownAt(ctx, svc, docID, insertIndex, markdown, c.Tab, true)
+	insertResult, err := insertPreparedDocsMarkdownAtWithWriteControl(
+		ctx,
+		svc,
+		docID,
+		insertIndex,
+		markdown,
+		c.Tab,
+		true,
+		docsRequiredRevisionWriteControl(requiredRevisionID),
+	)
 	if err != nil {
 		if isDocsNotFound(err) {
 			return fmt.Errorf("doc not found or not a Google Doc (id=%s)", docID)
diff --git a/internal/cmd/docs_insert_markdown_test.go b/internal/cmd/docs_insert_markdown_test.go
@@ -43,7 +43,8 @@ func TestDocsInsertCmd_MarkdownAtIndex(t *testing.T) {
 	flags := &RootFlags{Account: "a@b.com"}
 	ctx := withDocsTestService(newCmdRuntimeOutputContext(t, io.Discard, io.Discard), docSvc)
 
-	if err := runKong(t, &DocsInsertCmd{}, []string{"doc1", "## Heading", "--markdown", "--index", "7"}, ctx, flags); err != nil {
+	markdown := "## Heading\n\n```\ncode\n```"
+	if err := runKong(t, &DocsInsertCmd{}, []string{"doc1", markdown, "--markdown", "--index", "7"}, ctx, flags); err != nil {
 		t.Fatalf("insert --markdown: %v", err)
 	}
 
@@ -58,6 +59,7 @@ func TestDocsInsertCmd_MarkdownAtIndex(t *testing.T) {
 
 	var insertAtIndex *docs.InsertTextRequest
 	var sawHeadingStyle bool
+	var fencedCodeStyle *docs.UpdateTextStyleRequest
 	for _, req := range batchRequests[0] {
 		if req.InsertText != nil && req.InsertText.Location != nil && req.InsertText.Location.Index == 7 {
 			insertAtIndex = req.InsertText
@@ -67,6 +69,9 @@ func TestDocsInsertCmd_MarkdownAtIndex(t *testing.T) {
 			strings.HasPrefix(req.UpdateParagraphStyle.ParagraphStyle.NamedStyleType, "HEADING") {
 			sawHeadingStyle = true
 		}
+		if req.UpdateTextStyle != nil && strings.Contains(req.UpdateTextStyle.Fields, "weightedFontFamily") {
+			fencedCodeStyle = req.UpdateTextStyle
+		}
 	}
 	if insertAtIndex == nil {
 		t.Fatalf("expected an InsertText at index 7, requests: %#v", batchRequests[0])
@@ -77,6 +82,26 @@ func TestDocsInsertCmd_MarkdownAtIndex(t *testing.T) {
 	if !sawHeadingStyle {
 		t.Fatalf("expected a HEADING paragraph-style request from the markdown converter, requests: %#v", batchRequests[0])
 	}
+	assertFencedCodeTextStyle(t, fencedCodeStyle)
+}
+
+func TestDocsInsertCmd_MarkdownAtAnchorUsesRevisionControl(t *testing.T) {
+	t.Parallel()
+
+	rec := &docsAtAnchorRecorder{}
+	doc := docsFindRangeDoc(docsFindRangeParagraph(1, "Before anchor after\n"))
+	doc.RevisionId = "rev-markdown-anchor"
+	svc := setupDocsAtAnchorTestService(t, doc, rec)
+
+	flags := &RootFlags{Account: "a@b.com"}
+	ctx := withDocsTestService(newCmdRuntimeOutputContext(t, io.Discard, io.Discard), svc)
+	if err := runKong(t, &DocsInsertCmd{}, []string{"doc1", "## Heading", "--markdown", "--at", "anchor"}, ctx, flags); err != nil {
+		t.Fatalf("insert --markdown --at: %v", err)
+	}
+	if len(rec.batchRequests) != 1 {
+		t.Fatalf("batch calls = %d, want 1", len(rec.batchRequests))
+	}
+	assertDocsAtAnchorWriteControl(t, rec, 0, "rev-markdown-anchor")
 }
 
 // TestDocsInsertCmd_MarkdownRejectsBatch verifies the --markdown/--batch combo
diff --git a/internal/cmd/docs_mutation.go b/internal/cmd/docs_mutation.go
@@ -284,6 +284,19 @@ func insertPreparedDocsMarkdownAt(
 	markdown preparedMarkdown,
 	tabID string,
 	stripHeadingAnchors bool,
+) (docsMarkdownInsertResult, error) {
+	return insertPreparedDocsMarkdownAtWithWriteControl(ctx, svc, docID, insertIdx, markdown, tabID, stripHeadingAnchors, nil)
+}
+
+func insertPreparedDocsMarkdownAtWithWriteControl(
+	ctx context.Context,
+	svc *docs.Service,
+	docID string,
+	insertIdx int64,
+	markdown preparedMarkdown,
+	tabID string,
+	stripHeadingAnchors bool,
+	writeControl *docs.WriteControl,
 ) (docsMarkdownInsertResult, error) {
 	elements := docsmarkdown.ParseMarkdown(markdown.cleaned)
 	if stripHeadingAnchors {
@@ -321,7 +334,7 @@ func insertPreparedDocsMarkdownAt(
 	})
 	requests = append(requests, formattingRequests...)
 
-	requestCount, err := submitBatchedDocsRequests(ctx, svc, docID, requests, nil)
+	requestCount, err := submitBatchedDocsRequests(ctx, svc, docID, requests, writeControl)
 	if err != nil {
 		return docsMarkdownInsertResult{}, fmt.Errorf("append (markdown): %w", err)
 	}
