Add opt-in documentation link formatting (#107)

Let consumers retain navigation targets while keeping the default
link-stripping behavior. The variadic option changes the function
type, so stored function values may need updating.

Author: inancgumus

AGENTS.md

@@ -46,6 +46,11 @@
 - All internal doc links and remaining markdown links are stripped to plain text (URL removed).
 - Duplicate child names are deduplicated in search results.
 
+### Shared transform API
+- `docs.Transform(content, version, opts ...TransformOption)` accepts optional link formatting; its default still strips links, and the CLI continues to use that default until it updates its docs dependency.
+- `docs.WithLinkSlugs()` formats current-version k6 links as text followed by an inline slug and preserves other markdown links; custom options set exported `TransformOptions.FormatLink`.
+- This is a runtime transform; bundle generation and `mcp-k6` behavior remain unchanged, and existing bundles need no regeneration.
+
 ### Documentation version handling
 - Auto-detects k6 version from Go build info.
 - Maps to wildcard: `v1.5.0` → `v1.5.x`, `v1.6.0-rc.1` → `v1.6.x`.

docs/transform.go

@@ -1,6 +1,7 @@
 package docs
 
 import (
+	"net/url"
 	"regexp"
 	"strings"
 )
@@ -22,7 +23,7 @@ var (
 	reImageLink = regexp.MustCompile(`!\[([^\]]*)\]\([^)]+\)`)
 	// reMarkdownLink matches markdown links: [text](url)
 	// The text portion allows one level of nested brackets for cases like [get(url, [params])](url).
-	reMarkdownLink = regexp.MustCompile(`\[((?:[^\[\]]|\[[^\]]*\])*)\]\([^)]+\)`)
+	reMarkdownLink = regexp.MustCompile(`\[((?:[^\[\]]|\[[^\]]*\])*)\]\(([^)]+)\)`)
 )
 
 // PrepareTransform resolves docs/shared shortcodes using the shared content
@@ -46,10 +47,46 @@ func PrepareTransform(content string, sharedContent map[string]string) string {
 	})
 }
 
+// TransformOption configures optional markdown transformations.
+type TransformOption func(*TransformOptions)
+
+// TransformOptions controls markdown link formatting.
+type TransformOptions struct {
+	// FormatLink renders a link from its text, target URL, and documentation version.
+	FormatLink func(text, target, version string) string
+}
+
+// WithLinkSlugs shows current-version doc links as text followed by an inline
+// slug and preserves other markdown links, including web links.
+func WithLinkSlugs() TransformOption {
+	return func(opts *TransformOptions) {
+		opts.FormatLink = func(text, target, version string) string {
+			link := "[" + text + "](" + target + ")"
+			u, err := url.Parse(target)
+			if err != nil || u.Host != "" && u.Host != "grafana.com" {
+				return link
+			}
+			rest, ok := strings.CutPrefix(u.Path, "/docs/k6/")
+			if !ok {
+				return link
+			}
+			linkVersion, slug, ok := strings.Cut(rest, "/")
+			if !ok || VersionWildcard(linkVersion) != VersionWildcard(version) {
+				return link
+			}
+			slug = strings.Trim(slug, "/")
+			if slug == "" {
+				return link
+			}
+			return text + " (`" + slug + "`)"
+		}
+	}
+}
+
 // Transform applies markdown cleanup to content. It handles all pure text
 // transforms (shortcode stripping, admonition conversion, link stripping,
 // frontmatter removal, whitespace normalization). The pipeline runs in a
-// fixed order:
+// fixed order (WithLinkSlugs opts into inline doc slugs and preserved web links):
 //  1. Strip code tags
 //  2. Convert admonitions to blockquotes
 //  3. Strip section tags
@@ -63,10 +100,16 @@ func PrepareTransform(content string, sharedContent map[string]string) string {
 //  7. Strip HTML comments
 //  8. Strip YAML frontmatter
 //  9. Normalize whitespace
-func Transform(content, version string) string {
+func Transform(content, version string, opts ...TransformOption) string {
 	if content == "" {
 		return ""
 	}
+	options := TransformOptions{
+		FormatLink: func(text, _, _ string) string { return text },
+	}
+	for _, opt := range opts {
+		opt(&options)
+	}
 
 	s := content
 
@@ -118,8 +161,11 @@ func Transform(content, version string) string {
 	// 7. Strip markdown image links, keeping alt text.
 	s = reImageLink.ReplaceAllString(s, "$1")
 
-	// 7a. Strip remaining markdown links, keeping link text.
-	s = reMarkdownLink.ReplaceAllString(s, "$1")
+	// 7a. Apply the selected link formatter.
+	s = reMarkdownLink.ReplaceAllStringFunc(s, func(link string) string {
+		m := reMarkdownLink.FindStringSubmatch(link)
+		return options.FormatLink(m[1], m[2], version)
+	})
 
 	// 8. Strip HTML comments.
 	s = reHTMLComment.ReplaceAllString(s, "")

docs/transform_test.go

@@ -0,0 +1,19 @@
+package docs
+
+import "testing"
+
+func TestTransformWithLinkSlugs(t *testing.T) {
+	t.Parallel()
+
+	const input = `Refer to [Running k6](https://grafana.com/docs/k6/<K6_VERSION>/get-started/running-k6/).
+See [results](/docs/k6/v1.6.1/get-started/running-k6/?view=all#results).
+Keep [older docs](https://grafana.com/docs/k6/v1.5.x/get-started/running-k6/) and [other resources](https://example.com/docs/k6/v1.6.x/get-started/running-k6/).`
+	const want = "Refer to Running k6 (`get-started/running-k6`).\n" +
+		"See results (`get-started/running-k6`).\n" +
+		"Keep [older docs](https://grafana.com/docs/k6/v1.5.x/get-started/running-k6/) and " +
+		"[other resources](https://example.com/docs/k6/v1.6.x/get-started/running-k6/)."
+
+	if got := Transform(input, "v1.6.x", WithLinkSlugs()); got != want {
+		t.Errorf("Transform() = %q, want %q", got, want)
+	}
+}