feat(docs): add spacing mode to docs format (#886)

clawsweeper[bot] · Peter Steinberger · web-flow · commit cc86bfe0a00e · 2026-06-30T16:57:41.000-07:00
* feat(docs): add spacing mode to docs format

* feat(docs): add spacing mode to docs format

* feat(docs): add spacing mode to docs format

* docs: restore spacing mode changelog

---------

Co-authored-by: clawsweeper &lt;274271284+clawsweeper[bot]@users.noreply.github.com&gt;
Co-authored-by: Peter Steinberger &lt;steipete@golden-gate.local&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## 0.31.2 - Unreleased
 
+- Docs: add `docs format --spacing-mode` for setting paragraph spacing collapse behavior alongside `--space-above` and `--space-below`. (#885) — thanks @odyssey4me.
+
 ## 0.31.1 - 2026-06-26
 
 - Calendar: add `calendar changed` for listing recently modified events, including cancellations, across one or more calendars. (#875) — thanks @sorenisanerd.
diff --git a/docs/commands/gog-docs-format.md b/docs/commands/gog-docs-format.md
@@ -68,6 +68,7 @@ gog docs (doc) format <docId> [flags]
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
 | `--space-above` | `*float64` |  | Space above the paragraph in points |
 | `--space-below` | `*float64` |  | Space below the paragraph in points |
+| `--spacing-mode` | `string` |  | Paragraph spacing mode: NEVER_COLLAPSE or COLLAPSE_LISTS |
 | `--strikethrough`<br>`--strike` | `bool` |  | Set strikethrough |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
 | `--text-color` | `string` |  | Text color as #RRGGBB or #RGB |
diff --git a/docs/commands/gog-docs-write.md b/docs/commands/gog-docs-write.md
@@ -75,6 +75,7 @@ gog docs (doc) write <docId> [flags]
 | `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
 | `--space-above` | `*float64` |  | Space above the paragraph in points |
 | `--space-below` | `*float64` |  | Space below the paragraph in points |
+| `--spacing-mode` | `string` |  | Paragraph spacing mode: NEVER_COLLAPSE or COLLAPSE_LISTS |
 | `--strikethrough`<br>`--strike` | `bool` |  | Set strikethrough |
 | `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
 | `--text` | `string` |  | Text to write |
diff --git a/docs/docs-editing.md b/docs/docs-editing.md
@@ -77,11 +77,13 @@ gog docs format <docId> --match "Action item" --no-bullets
 ```
 
 Paragraph layout controls use points and accept explicit zero values. Boolean
-keep controls have matching `--no-...` forms:
+keep controls have matching `--no-...` forms. `--spacing-mode` accepts the
+Docs API values `NEVER_COLLAPSE` and `COLLAPSE_LISTS` case-insensitively:
 
 ```bash
 gog docs format <docId> --match "Summary" --indent-start 24 --indent-first-line 12
 gog docs format <docId> --match "Summary" --space-above 6 --space-below 12 --keep-with-next
+gog docs format <docId> --match "Action item" --space-below 6 --spacing-mode NEVER_COLLAPSE
 gog docs format <docId> --match "Summary" --no-keep-with-next --keep-lines-together
 ```
 
diff --git a/internal/cmd/docs_format.go b/internal/cmd/docs_format.go
@@ -44,6 +44,7 @@ type DocsFormatFlags struct {
 	NoStrike          bool     `name:"no-strikethrough" aliases:"no-strike" help:"Clear strikethrough"`
 	Alignment         string   `name:"alignment" help:"Paragraph alignment: left, center, right, justify, start, end, justified"`
 	LineSpacing       float64  `name:"line-spacing" help:"Paragraph line spacing percentage, for example 100 or 150"`
+	SpacingMode       string   `name:"spacing-mode" help:"Paragraph spacing mode: NEVER_COLLAPSE or COLLAPSE_LISTS"`
 	HeadingLevel      *int     `name:"heading-level" help:"Set paragraph named style to HEADING_1..HEADING_6 (shortcut for --named-style=HEADING_N)"`
 	NamedStyle        string   `name:"named-style" help:"Set paragraph named style: NORMAL_TEXT, TITLE, SUBTITLE, HEADING_1..HEADING_6"`
 	Bullets           bool     `name:"bullets" help:"Create a bulleted list with the default disc preset"`
@@ -123,6 +124,7 @@ func (c *DocsFormatCmd) Run(ctx context.Context, flags *RootFlags) error {
 			"no_strike":           c.Format.NoStrike,
 			"alignment":           c.Format.Alignment,
 			"line_spacing":        c.Format.LineSpacing,
+			"spacing_mode":        c.Format.SpacingMode,
 			"heading_level":       c.Format.HeadingLevel,
 			"named_style":         c.Format.NamedStyle,
 			"bullets":             c.Format.Bullets,
@@ -399,7 +401,8 @@ func (f DocsFormatFlags) createsBullets() bool {
 
 func (f DocsFormatFlags) hasParagraphStyle() bool {
 	return strings.TrimSpace(f.Alignment) != "" || f.LineSpacing != 0 || f.HeadingLevel != nil ||
-		strings.TrimSpace(f.NamedStyle) != "" || f.IndentStart != nil || f.IndentFirstLine != nil ||
+		strings.TrimSpace(f.SpacingMode) != "" || strings.TrimSpace(f.NamedStyle) != "" ||
+		f.IndentStart != nil || f.IndentFirstLine != nil ||
 		f.IndentEnd != nil || f.SpaceAbove != nil || f.SpaceBelow != nil ||
 		f.KeepWithNext != nil || f.KeepLinesTogether != nil
 }
@@ -429,6 +432,7 @@ func (f DocsFormatFlags) paragraphOnly() DocsFormatFlags {
 	return DocsFormatFlags{
 		Alignment:         f.Alignment,
 		LineSpacing:       f.LineSpacing,
+		SpacingMode:       f.SpacingMode,
 		HeadingLevel:      f.HeadingLevel,
 		NamedStyle:        f.NamedStyle,
 		Bullets:           f.Bullets,
@@ -483,6 +487,7 @@ func (f DocsFormatFlags) options() docsformat.Options {
 		ClearStrike:       f.NoStrike,
 		Alignment:         f.Alignment,
 		LineSpacing:       f.LineSpacing,
+		SpacingMode:       f.SpacingMode,
 		HeadingLevel:      f.HeadingLevel,
 		NamedStyle:        f.NamedStyle,
 		Bullets:           f.Bullets,
diff --git a/internal/cmd/docs_format_test.go b/internal/cmd/docs_format_test.go
@@ -26,6 +26,7 @@ func TestDocsFormatFlagsBuildRequests(t *testing.T) {
 		Italic:      true,
 		Alignment:   "center",
 		LineSpacing: 150,
+		SpacingMode: "collapse_lists",
 	}).buildRequests(3, 9, "t.second")
 	if err != nil {
 		t.Fatalf("buildRequests: %v", err)
@@ -65,7 +66,8 @@ func TestDocsFormatFlagsBuildRequests(t *testing.T) {
 		t.Fatalf("missing paragraph request: %#v", reqs[1])
 		return
 	}
-	if paraReq.ParagraphStyle.Alignment != "CENTER" || paraReq.ParagraphStyle.LineSpacing != 150 {
+	if paraReq.ParagraphStyle.Alignment != "CENTER" || paraReq.ParagraphStyle.LineSpacing != 150 ||
+		paraReq.ParagraphStyle.SpacingMode != docsformat.SpacingModeCollapseLists {
 		t.Fatalf("unexpected paragraph style: %#v", paraReq.ParagraphStyle)
 	}
 	if got := paraReq.Range; got.TabId != "t.second" {
@@ -118,6 +120,9 @@ func TestDocsFormatFlagsValidation(t *testing.T) {
 	if _, err := (DocsFormatFlags{Alignment: "sideways"}).buildRequests(1, 2, ""); err == nil {
 		t.Fatalf("expected invalid alignment error")
 	}
+	if _, err := (DocsFormatFlags{SpacingMode: "sometimes"}).buildRequests(1, 2, ""); err == nil {
+		t.Fatalf("expected invalid spacing-mode error")
+	}
 	if _, err := (DocsFormatFlags{Code: true, FontFamily: "Arial"}).buildRequests(1, 2, ""); err == nil {
 		t.Fatalf("expected conflicting code/font-family flags error")
 	}
@@ -330,6 +335,7 @@ func TestDocsFormatCmdParagraphControls(t *testing.T) {
 	err := runKong(t, &DocsFormatCmd{}, []string{
 		"doc1", "--match", "Alpha", "--match-all", "--bold", "--ordered",
 		"--indent-start", "24", "--space-below", "6",
+		"--spacing-mode", "never_collapse",
 		"--keep-with-next", "--no-keep-lines-together",
 	}, ctx, flags)
 	if err != nil {
@@ -351,6 +357,7 @@ func TestDocsFormatCmdParagraphControls(t *testing.T) {
 		t.Fatalf("grouped paragraph requests: %#v", batchRequests[0])
 	}
 	if paragraph.ParagraphStyle.IndentStart.Magnitude != 24 || paragraph.ParagraphStyle.SpaceBelow.Magnitude != 6 ||
+		paragraph.ParagraphStyle.SpacingMode != docsformat.SpacingModeNeverCollapse ||
 		!paragraph.ParagraphStyle.KeepWithNext || paragraph.ParagraphStyle.KeepLinesTogether {
 		t.Fatalf("unexpected paragraph style: %#v", paragraph.ParagraphStyle)
 	}
diff --git a/internal/cmd/dryrun_e2e_test.go b/internal/cmd/dryrun_e2e_test.go
@@ -89,7 +89,7 @@ func TestDryRunE2E_CommandsSkipAuthAPIAndFileWrites(t *testing.T) {
 		},
 		{
 			name: "docs format",
-			args: []string{"docs", "format", "doc123", "--bold"},
+			args: []string{"docs", "format", "doc123", "--spacing-mode", "collapse_lists"},
 			op:   "docs.format",
 		},
 		{
@@ -894,10 +894,18 @@ func TestDryRunE2E_ValidatesFormsAndSheetsLocalInputs(t *testing.T) {
 			name: "docs write validates format flags before dry-run",
 			args: []string{"docs", "write", "doc123", "--text", "hello", "--font-size", "-1"},
 		},
+		{
+			name: "docs write validates spacing mode before dry-run",
+			args: []string{"docs", "write", "doc123", "--text", "hello", "--spacing-mode", "sometimes"},
+		},
 		{
 			name: "docs format validates colors before dry-run",
 			args: []string{"docs", "format", "doc123", "--text-color", "nope"},
 		},
+		{
+			name: "docs format validates spacing mode before dry-run",
+			args: []string{"docs", "format", "doc123", "--spacing-mode", "sometimes"},
+		},
 	}
 
 	for _, tc := range cases {
diff --git a/internal/docsedit/planner.go b/internal/docsedit/planner.go
@@ -71,7 +71,8 @@ func createsParagraphBullets(options docsformat.Options) bool {
 
 func hasParagraphStyle(options docsformat.Options) bool {
 	return strings.TrimSpace(options.Alignment) != "" || options.LineSpacing != 0 || options.HeadingLevel != nil ||
-		strings.TrimSpace(options.NamedStyle) != "" || options.IndentStart != nil || options.IndentFirstLine != nil ||
+		strings.TrimSpace(options.SpacingMode) != "" || strings.TrimSpace(options.NamedStyle) != "" ||
+		options.IndentStart != nil || options.IndentFirstLine != nil ||
 		options.IndentEnd != nil || options.SpaceAbove != nil || options.SpaceBelow != nil ||
 		options.KeepWithNext != nil || options.KeepLinesTogether != nil
 }
diff --git a/internal/docsedit/planner_test.go b/internal/docsedit/planner_test.go
@@ -64,15 +64,13 @@ func TestBuildWriteRequestsAppendSkipsDelete(t *testing.T) {
 }
 
 func TestBuildWriteRequestsBulletsAdjustParagraphRangeAfterTabs(t *testing.T) {
-	indent := 54.0
-
 	requests, err := BuildWriteRequests(WriteOptions{
 		EndIndex:    1,
 		InsertIndex: 1,
 		Text:        "\tFirst\n\t\tSecond\n",
 		Format: docsformat.Options{
 			Ordered:     true,
-			IndentStart: &indent,
+			SpacingMode: docsformat.SpacingModeCollapseLists,
 		},
 	})
 	if err != nil {
@@ -86,6 +84,10 @@ func TestBuildWriteRequestsBulletsAdjustParagraphRangeAfterTabs(t *testing.T) {
 	if got := requests[2].UpdateParagraphStyle.Range; got.StartIndex != 1 || got.EndIndex != 14 {
 		t.Fatalf("post-bullet paragraph range = %#v, want 1..14", got)
 	}
+
+	if got := requests[2].UpdateParagraphStyle.ParagraphStyle.SpacingMode; got != docsformat.SpacingModeCollapseLists {
+		t.Fatalf("spacing mode = %q, want %q", got, docsformat.SpacingModeCollapseLists)
+	}
 }
 
 func TestBuildWriteRequestsEmptyBodySkipsDelete(t *testing.T) {
diff --git a/internal/docsformat/format.go b/internal/docsformat/format.go
@@ -27,6 +27,11 @@ const (
 	namedStyleHeading6   = "HEADING_6"
 )
 
+const (
+	SpacingModeNeverCollapse = "NEVER_COLLAPSE"
+	SpacingModeCollapseLists = "COLLAPSE_LISTS"
+)
+
 type ValidationError string
 
 func (e ValidationError) Error() string {
@@ -52,6 +57,7 @@ type Options struct {
 	ClearStrike       bool
 	Alignment         string
 	LineSpacing       float64
+	SpacingMode       string
 	HeadingLevel      *int
 	NamedStyle        string
 	Bullets           bool
@@ -85,6 +91,7 @@ func (o Options) Any() bool {
 		o.Strikethrough || o.ClearStrike ||
 		strings.TrimSpace(o.Alignment) != "" ||
 		o.LineSpacing != 0 ||
+		strings.TrimSpace(o.SpacingMode) != "" ||
 		o.HeadingLevel != nil ||
 		strings.TrimSpace(o.NamedStyle) != "" ||
 		o.Bullets || o.Ordered || strings.TrimSpace(o.BulletPreset) != "" || o.ClearBullets ||
@@ -292,6 +299,16 @@ func buildParagraphStyleRequest(options Options, start, end int64, tabID string)
 		fields = append(fields, "lineSpacing")
 	}
 
+	if spacingMode := strings.TrimSpace(options.SpacingMode); spacingMode != "" {
+		resolved, err := formatSpacingMode(spacingMode)
+		if err != nil {
+			return nil, false, err
+		}
+		style.SpacingMode = resolved
+
+		fields = append(fields, "spacingMode")
+	}
+
 	namedStyle, err := formatNamedStyle(options.HeadingLevel, options.NamedStyle)
 	if err != nil {
 		return nil, false, err
@@ -442,6 +459,17 @@ func validBulletPreset(value string) bool {
 	}
 }
 
+func formatSpacingMode(value string) (string, error) {
+	switch strings.ToUpper(strings.TrimSpace(value)) {
+	case SpacingModeNeverCollapse:
+		return SpacingModeNeverCollapse, nil
+	case SpacingModeCollapseLists:
+		return SpacingModeCollapseLists, nil
+	default:
+		return "", ValidationError("--spacing-mode must be NEVER_COLLAPSE or COLLAPSE_LISTS")
+	}
+}
+
 func formatLink(value string) (*docs.Link, error) {
 	link := strings.TrimSpace(value)
 	if link == "" {
diff --git a/internal/docsformat/format_test.go b/internal/docsformat/format_test.go
@@ -81,6 +81,10 @@ func TestOptionsAny(t *testing.T) {
 	if !(Options{SpaceBelow: floatPointer(0)}).Any() {
 		t.Fatal("explicit zero dimension should count as formatting")
 	}
+
+	if !(Options{SpacingMode: SpacingModeNeverCollapse}).Any() {
+		t.Fatal("spacing mode should count as formatting")
+	}
 }
 
 func TestBuildRequestsParagraphControlsAndBullets(t *testing.T) {
@@ -91,6 +95,7 @@ func TestBuildRequestsParagraphControlsAndBullets(t *testing.T) {
 		IndentEnd:         floatPointer(0),
 		SpaceAbove:        floatPointer(6),
 		SpaceBelow:        floatPointer(12),
+		SpacingMode:       "never_collapse",
 		KeepWithNext:      boolPointer(true),
 		KeepLinesTogether: boolPointer(false),
 	}, 3, 20, "t.second")
@@ -107,13 +112,14 @@ func TestBuildRequestsParagraphControlsAndBullets(t *testing.T) {
 		t.Fatalf("missing paragraph request: %#v", requests[0])
 	}
 
-	if paragraph.Fields != "indentStart,indentFirstLine,indentEnd,spaceAbove,spaceBelow,keepWithNext,keepLinesTogether" {
+	if paragraph.Fields != "spacingMode,indentStart,indentFirstLine,indentEnd,spaceAbove,spaceBelow,keepWithNext,keepLinesTogether" {
 		t.Fatalf("fields = %q", paragraph.Fields)
 	}
 
 	style := paragraph.ParagraphStyle
 	if style.IndentStart.Magnitude != 36 || style.IndentFirstLine.Magnitude != 18 || style.IndentEnd.Magnitude != 0 ||
-		style.SpaceAbove.Magnitude != 6 || style.SpaceBelow.Magnitude != 12 || !style.KeepWithNext || style.KeepLinesTogether {
+		style.SpaceAbove.Magnitude != 6 || style.SpaceBelow.Magnitude != 12 || style.SpacingMode != SpacingModeNeverCollapse ||
+		!style.KeepWithNext || style.KeepLinesTogether {
 		t.Fatalf("unexpected paragraph style: %#v", style)
 	}
 
@@ -215,6 +221,7 @@ func TestBuildRequestsParagraphControlValidation(t *testing.T) {
 		{Bullets: true, Ordered: true},
 		{Bullets: true, ClearBullets: true},
 		{BulletPreset: "not_a_preset"},
+		{SpacingMode: "sometimes"},
 	}
 	for _, options := range tests {
 		if _, err := BuildRequests(options, 1, 2, ""); err == nil {

Original file line number	Diff line number	Diff line change
`@@ -71,7 +71,8 @@ func createsParagraphBullets(options docsformat.Options) bool {`
`71`	`71`
`72`	`72`	`func hasParagraphStyle(options docsformat.Options) bool {`
`73`	`73`	`return strings.TrimSpace(options.Alignment) != "" \|\| options.LineSpacing != 0 \|\| options.HeadingLevel != nil \|\|`
`74`		`- strings.TrimSpace(options.NamedStyle) != "" \|\| options.IndentStart != nil \|\| options.IndentFirstLine != nil \|\|`
	`74`	`+ strings.TrimSpace(options.SpacingMode) != "" \|\| strings.TrimSpace(options.NamedStyle) != "" \|\|`
	`75`	`+ options.IndentStart != nil \|\| options.IndentFirstLine != nil \|\|`
`75`	`76`	`options.IndentEnd != nil \|\| options.SpaceAbove != nil \|\| options.SpaceBelow != nil \|\|`
`76`	`77`	`options.KeepWithNext != nil \|\| options.KeepLinesTogether != nil`
`77`	`78`	`}`