Wrap markdown generated help output links in markdown syntax

Problem Statement

The GitLab CLI (glab) prioritizes command-line --help output when creating help documentation. This creates an issue where URLs appear as "bare" text in the terminal (which is appropriate for CLI output), but when the documentation generator (cmd/gen-docs/docs.go) converts this content to markdown files for the docs site, these bare URLs remain unwrapped.

Current behavior:

  * In internal/commands/root.go, the help:environment annotation contains bare URLs like:
      * https://docs.gitlab.com/administration/settings/usage_statistics/

      * https://github.com/charmbracelet/glamour#styles
  * These appear correctly in terminal output
  * In generated markdown (docs/source/_index.md), they appear as plain text within table cells, which doesn't follow markdown

best practices

Proposed Solution

Implement URL detection and wrapping in the documentation generator (cmd/gen-docs/docs.go) to automatically convert bare URLs into proper markdown link syntax URL during the generation process.

Implementation Approach

  1. Add URL Detection Function Create a helper function to detect URLs using a regular expression pattern:

    func detectAndWrapURLs(text string) string { // Match http:// or https:// URLs urlPattern := regexp.MustCompile((https?://[^\s\)]+))

     // Replace bare URLs with markdown link syntax
 return urlPattern.ReplaceAllString(text, "[$1]($1)")

    }

  2. Apply URL Wrapping in Key Locations

The function should be applied in these specific areas of cmd/gen-docs/docs.go:

  * Environment Variables Table (in GenRootMarkdownCustom): When processing the help:environment annotation and building the

table, wrap URLs in the description column * Command Descriptions (in GenMarkdownCustom): Process cmd.Long and cmd.Short fields * Examples (in GenMarkdownCustom): Process cmd.Example field * Options/Flags: Process flag descriptions from flags.PrintDefaults()

  1. Preserve Existing Markdown Links

The regex should be refined to avoid double-wrapping already-formatted markdown links:

  func detectAndWrapURLs(text string) string {
      // Match URLs that are NOT already wrapped in markdown syntax
      // Negative lookbehind for '](' and negative lookahead for being inside []()
      urlPattern := regexp.MustCompile(`(?<!\]\()https?://[^\s\)\]]+(?!\))`)

      return urlPattern.ReplaceAllString(text, "[$0]($0)")
  }

Benefits 

  1. Consistency: Generated markdown documentation will follow proper markdown conventions
  2. Better UX: URLs in the docs site will be clickable links
  3. Maintainability: No need to maintain separate help text for CLI vs docs
  4. Backward Compatible: Terminal output remains unchanged (bare URLs work fine in terminals)
  5. Automated: Works for all current and future URLs added to help text

Potential Challenges 

  1. URL Detection Edge Cases:


      * URLs with special characters (parentheses, brackets)

      * URLs at end of sentences with punctuation

      * Fragment identifiers (#) in URLs

     Mitigation: Use comprehensive regex testing and handle common edge cases
  2. Already-Formatted Links:


      * Need to avoid double-wrapping URLs that are already in markdown format

     Mitigation: Use negative lookahead/lookbehind in regex pattern
  3. Performance:


      * Regex processing on all text content

     Mitigation: Documentation generation is a one-time build step, so performance impact is minimal

Testing Strategy 

  1. Add unit tests for the detectAndWrapURLs function with various URL formats
  2. Test with existing URLs in root.go
  3. Verify generated markdown renders correctly
  4. Ensure terminal --help output remains unchanged
  5. Test edge cases (URLs with fragments, query parameters, etc.)

Feasibility Assessment

✅ Highly Feasible

  * The codebase already has a clear separation between help text generation and markdown generation
  * The cmd/gen-docs/docs.go file is well-structured and easy to modify
  * Go's regexp package provides robust URL matching capabilities
  * The change is isolated to the documentation generator, minimizing risk
  * No changes needed to existing help text in command definitions

Recommendation

This enhancement is both feasible and valuable. It would improve the quality of generated documentation while maintaining the current developer experience for writing help text. The implementation is straightforward and can be completed with minimal risk to existing functionality.

Edited by Kai Armstrong