Add --mintlify flag to kosli docs command

[dangrondahl]

Summary

The kosli docs command (in cmd/kosli/docs.go) currently generates Hugo-format markdown. Add a --mintlify flag (default: false) that generates Mintlify-compatible MDX markdown instead.

Context

The Kosli docs are being migrated from Hugo to Mintlify. With a --mintlify flag, the CLI can directly produce Mintlify-ready files:

kosli docs --dir client_reference/ --mintlify

What needs to change in docs.go

1. Front matter format

Current (Hugo):

---
title: "kosli attest jira"
beta: false
deprecated: false
summary: "Report a jira attestation..."
---

Mintlify:

---
title: "kosli attest jira"
beta: false
deprecated: false
description: "Report a jira attestation..."
---

• Keep beta and deprecated fields (Mintlify supports custom front matter fields)
• Rename summary → description
• Sanitize description: replace ^text^ with `text`, truncate to first sentence if >200 chars (long descriptions with special chars cause MDX parsing issues)

2. Hint shortcodes → MDX components

Current:

{{% hint info %}} ... {{% /hint %}}
{{% hint warning %}} ... {{% /hint %}}
{{% hint danger %}} ... {{% /hint %}}
{{% hint success %}} ... {{% /hint %}}

Mintlify:

<Info> ... </Info>
<Warning> ... </Warning>
<Warning> ... </Warning>
<Tip> ... </Tip>

Relevant code: lines ~119–133 in docs.go (requiredFlagsNote, defaultedFlagsNote, optionalFlagsNote, conditionalFlagsNote).

3. Tabs shortcodes → MDX components

Current (inline):

{{< tabs "id" >}}{{< tab "Title" >}}content{{< /tab >}}{{< /tabs >}}

Mintlify (must be on separate lines):

<Tabs>
	<Tab title="Title">
content
	</Tab>
</Tabs>

Critical: MDX requires Tab/Tabs components on their own lines — inline formatting causes parsing errors.

Relevant code: lines ~152–167 in docs.go (live examples generation).

4. Raw HTML shortcodes

Current:

{{< raw-html >}}<pre>...</pre>{{< /raw-html >}}

Mintlify: Strip the shortcode wrappers, output raw HTML directly.

Relevant code: lines ~172–179 in docs.go.

5. Example headings → Accordion components

Current:

##### example title

\```shell
kosli command --flag value
\```

Mintlify:

<AccordionGroup>
	<Accordion title="example title">

	```shell
	kosli command --flag value
	```

	</Accordion>
</AccordionGroup>

6. Escape JSX-sensitive characters in prose

MDX interprets {expression} as JSX and <Word> as components. In prose text (outside code blocks), these must be escaped:

• {YYYY-MM-DDTHH:MM:SS} → \{YYYY-MM-DDTHH:MM:SS\}
• {N.hours.ago} → \{N.hours.ago\}
• <ENVIRONMENT_NAME> → `ENVIRONMENT_NAME`
• <fingerprint> → `fingerprint`
• {{ github.head_ref }} → \{\{ github.head_ref \}\}
• <v2.8.2 → \<v2.8.2

This only applies to prose — content inside ``` code blocks is fine.

7. Other conversions

• Strip {.command} from code fences: ```shell {.command} → ```shell
• Convert {{< ref "/path" >}} → /path
• Convert {{< cli-version >}} → actual version string or placeholder
• Remove https://docs.kosli.com prefix from internal links
• Remove trailing slashes from internal link paths

Implementation suggestion

Add a --mintlify boolean flag to the docs command. In the doc generation functions, check this flag to decide which format to output. The changes are mostly in:

• headerFunc — front matter format
• requiredFlagsNote / defaultedFlagsNote / optionalFlagsNote / conditionalFlagsNote — hint → MDX components
• Live examples section — tabs → MDX components, raw-html removal
• Example use cases section — ##### headings → Accordion components
• A post-processing pass for JSX escaping in prose

Validation

The full set of conversion rules was discovered by testing all 92 CLI reference pages on a local Mintlify dev server (mint dev). Each rule above addresses a specific MDX parsing error that was identified and fixed.