## Problem The CLI documentation is auto-generated from `.go` files, where the same text is used for both: - Terminal `help` text output - Generated Markdown documentation files This creates a formatting conflict for links: - **Terminal**: Should display plain text URLs (e.g., `https://docs.gitlab.com/...`) - **Documentation**: Should use proper Markdown link syntax (e.g., `[link text](URL)`) Currently, we're forced to use plain URLs everywhere, which looks unprofessional in the generated documentation. ## Current state As seen in [MR !2735](https://gitlab.com/gitlab-org/cli/-/merge_requests/2735#note_3009409195), we have to write help text like: ``` For a list of supported commands, see the CI/CD job token documentation: https://docs.gitlab.com/ci/jobs/ci_job_token/#job-token-access. ``` This appears as a raw URL in both terminal and docs, when ideally the docs would show: ```markdown For a list of supported commands, see the [CI/CD job token documentation](https://docs.gitlab.com/ci/jobs/ci_job_token/#job-token-access). ``` ## Solution Implemented in [!3189](https://gitlab.com/gitlab-org/cli/-/merge_requests/3189): render Markdown links as OSC 8 hyperlinks in help text. When command `Long` descriptions contain Markdown links (`[text](url)`), they are converted to [OSC 8 hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) before Fang renders help output. OSC 8 is the terminal standard for clickable links, supported by iTerm2, Kitty, WezTerm, GNOME Terminal, Windows Terminal, and others. - In terminals that **do not support OSC 8**, the sequences are silently ignored and only the link text is shown. - When output is **piped or redirected**, Fang's `colorprofile.Writer` strips the sequences automatically. This means command descriptions can now be written using standard Markdown link syntax (`[text](url)`) and they will render correctly in both the terminal and the generated documentation. ### Implementation details Two conversion functions were added to `internal/text`: - `ConvertMarkdownLinksToOSC8(s string) string`: Converts `[text](url)` to OSC 8 sequences. - `ConvertOSC8ToMarkdown(s string) string`: Reverse conversion (for future use in `gen-docs`). In `cmd/glab/main.go`, a `preprocessCommandLinks` helper walks the full command tree immediately before `fang.Execute` is called, converting all `Long` fields in place. No per-command changes are required — any command that already uses `[text](url)` syntax in its description gets clickable links automatically. ## Related - Original discussion: https://gitlab.com/gitlab-org/cli/-/merge_requests/2735#note_3009409195 - Example MR showing the problem: [!2735](https://gitlab.com/gitlab-org/cli/-/merge_requests/2735) - Implementation: [!3189](https://gitlab.com/gitlab-org/cli/-/merge_requests/3189)