From 9c67bb2c11f721ebbf5dca8faa58a1210339f9c6 Mon Sep 17 00:00:00 2001
From: Marko Bevc <marko@kosli.com>
Date: Fri, 10 Jul 2026 12:25:12 +0100
Subject: [PATCH] fix(docs): escape double quotes in Mintlify accordion example
 titles

The generated MDX for a command whose example comment contains double
quotes (e.g. 'kosli list controls' with: # list controls whose name or
identifier contains "sdlc") produced an invalid JSX attribute:

  <Accordion title="... contains "sdlc"">

which breaks the Mintlify build for that page, so the page fails to
render and its BETA sidebar tag is lost. Replace double quotes with
single quotes when writing accordion titles.
---
 internal/docgen/mintlify.go      |  2 ++
 internal/docgen/mintlify_test.go | 12 ++++++++++++
 2 files changed, 14 insertions(+)

diff --git a/internal/docgen/mintlify.go b/internal/docgen/mintlify.go
index 768894669..9a7dc0cf9 100644
--- a/internal/docgen/mintlify.go
+++ b/internal/docgen/mintlify.go
@@ -121,6 +121,8 @@ func (MintlifyFormatter) ExampleUseCases(commandName, example string) string {
 			exampleLines := all[i]
 			title := strings.Trim(exampleLines[0], ":")
 			if len(title) > 0 {
+				// Double quotes would terminate the JSX title attribute and break the MDX build.
+				title = strings.ReplaceAll(title, "\"", "'")
 				fmt.Fprintf(&b, "<Accordion title=\"%s\">\n", strings.TrimSpace(title[1:]))
 				fmt.Fprintf(&b, "```shell\n%s\n```\n", strings.Join(exampleLines[1:], "\n"))
 				b.WriteString("</Accordion>\n")
diff --git a/internal/docgen/mintlify_test.go b/internal/docgen/mintlify_test.go
index 4949d3b8b..b579521f6 100644
--- a/internal/docgen/mintlify_test.go
+++ b/internal/docgen/mintlify_test.go
@@ -163,6 +163,18 @@ func TestMintlifyExampleUseCases(t *testing.T) {
 	}
 }
 
+func TestMintlifyExampleUseCasesEscapesQuotesInTitle(t *testing.T) {
+	f := MintlifyFormatter{}
+	example := "# list controls whose name or identifier contains \"sdlc\":\nkosli list controls --search sdlc"
+	got := f.ExampleUseCases("kosli list controls", example)
+	if !strings.Contains(got, `<Accordion title="list controls whose name or identifier contains 'sdlc'">`) {
+		t.Errorf("expected double quotes in title to be replaced with single quotes, got:\n%s", got)
+	}
+	if strings.Contains(got, `contains "sdlc"`) {
+		t.Errorf("expected no raw double quotes inside the title attribute, got:\n%s", got)
+	}
+}
+
 func TestMintlifyLinkHandler(t *testing.T) {
 	f := MintlifyFormatter{}
 	got := f.LinkHandler("kosli_attest_snyk.md")