Show documentation paths beside internal links (#108)

Keep documentation references usable in the terminal by displaying
copyable paths and retaining web links.

Author: inancgumus

.agents/features.md

@@ -115,7 +115,7 @@ Every user-observable behavior of the `k6 x docs` CLI.
 88. Strips remaining Hugo shortcodes (youtube, card-grid, collapse, hero-simple)
 89. Collapse content preserved (only tags stripped)
 90. Replaces `<K6_VERSION>` with actual version
-91. Strips markdown links to plain text
+91. The CLI opts into shared `docs.Transform` link formatting with `WithLinkSlugs()`: current-version Grafana k6 doc slugs appear in parentheses and backticks after the link text; supports absolute and `/docs/k6/` URLs, matches patch versions to their wildcard version, and drops query strings/fragments from slugs; other markdown links retain their URLs; default shared behavior, existing bundles, and `mcp-k6` remain unchanged; custom options can set exported `TransformOptions.FormatLink`
 92. Strips markdown images to alt text
 93. Strips HTML comments
 94. Strips PascalCase component tags (`<Glossary>`, `<DescriptionList>`, etc.)

go.mod

@@ -6,7 +6,7 @@ require (
 	github.com/charmbracelet/glamour v1.0.0
 	github.com/creack/pty v1.1.24
 	github.com/go-git/go-git/v5 v5.19.2
-	github.com/grafana/xk6-docs/docs v0.1.0
+	github.com/grafana/xk6-docs/docs v0.2.0
 	github.com/klauspost/compress v1.19.2
 	github.com/muesli/termenv v0.16.0
 	github.com/rogpeppe/go-internal v1.14.1

go.sum

@@ -159,8 +159,8 @@ github.com/grafana/sobek-webapi-encoding v0.1.0 h1:2qf2pUiI6j33vl2etSE0Id4mfSQ4J
 github.com/grafana/sobek-webapi-encoding v0.1.0/go.mod h1:IegnWm83cyZ8qTnfL6Rivmx7dpMVE+w3CblopwfL/go=
 github.com/grafana/xk6-dashboard-assets v0.1.2 h1:n2wqytPICn2ZYsKa9HE6GlvFXk+WjByMfT4eM+ms3gE=
 github.com/grafana/xk6-dashboard-assets v0.1.2/go.mod h1:SeoRjvmFF8UhLIFDfvjqqwBtE8MtaIPYIDWqVJZEHDo=
-github.com/grafana/xk6-docs/docs v0.1.0 h1:2f9S1qF/VeF9kG+tcLGrI6UMkoQRSSSj45GkDeJX80E=
-github.com/grafana/xk6-docs/docs v0.1.0/go.mod h1:IBgZ0BW2xy2hhKaI+pGd/n4Gvi4FfUdR0/YQAVmKYUU=
+github.com/grafana/xk6-docs/docs v0.2.0 h1:/IIGby8JmG5rVy3emz+BxKH6P50klacZLrU4Rug6oe0=
+github.com/grafana/xk6-docs/docs v0.2.0/go.mod h1:6Vi1nQJjNX57ZNWPsFq7TALQyy1aPCeR+Ep2eo0jZow=
 github.com/grpc-ecosystem/go-grpc-middleware v1.4.0 h1:UH//fgunKIs4JdUbpDl1VZCDaL56wXCB/5+wF6uHfaI=
 github.com/grpc-ecosystem/go-grpc-middleware v1.4.0/go.mod h1:g5qyo/la0ALbONm6Vbp88Yd8NsDy6rZz+RcrMPxvld8=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 h1:5VipnvEpbqr2gA2VbM+nYVbkIF28c5ZQfqCBQ5g2xfk=

internal/cli/bundle.go

@@ -29,7 +29,7 @@ func (env *docsEnv) readAndTransform(ctx context.Context, slug string) string {
 	if err != nil {
 		return ""
 	}
-	return docs.Transform(string(data), env.version)
+	return docs.Transform(string(data), env.version, docs.WithLinkSlugs())
 }
 
 // setup resolves the version, ensures docs are cached, and loads the index.
@@ -180,7 +180,7 @@ func printBestPractices(ctx context.Context, env *docsEnv, w io.Writer) error {
 	if err != nil {
 		return fmt.Errorf("read best practices: %w", err)
 	}
-	content := docs.Transform(string(data), env.version)
+	content := docs.Transform(string(data), env.version, docs.WithLinkSlugs())
 	_, _ = fmt.Fprint(w, content)
 	if !strings.HasSuffix(content, "\n") {
 		_, _ = fmt.Fprintln(w)

internal/clitest/testdata/scripts/links.txtar

@@ -0,0 +1,45 @@
+# Internal links show a copyable slug; external links retain their URL.
+exec ./k6 x docs --cache-dir $WORK/links --version v1.6.x get-started write-your-first-test
+cmp stdout expected.md
+
+# TTY output, search navigation, and the best-practices page share the transform.
+env NO_COLOR=1
+ptyexec ./k6 x docs --cache-dir $WORK/links --version v1.6.x get-started write-your-first-test
+cp stdout tty.md
+containslines expected.md tty.md
+exec ./k6 x docs --cache-dir $WORK/links --version v1.6.x search get-started/write-your-first-test
+cmp stdout expected.md
+cp links/v1.6.x/markdown/first.md links/v1.6.x/best_practices.md
+exec ./k6 x docs --cache-dir $WORK/links --version v1.6.x best-practices
+cmp stdout expected.md
+
+# Local source previews keep links through bundle preparation too.
+mkdir src/docs/sources/k6/v1.6.x/get-started
+cp links/v1.6.x/markdown/first.md src/docs/sources/k6/v1.6.x/get-started/write-your-first-test.md
+cp links/v1.6.x/markdown/running.md src/docs/sources/k6/v1.6.x/get-started/running-k6.md
+cp index.md src/docs/sources/k6/v1.6.x/get-started/_index.md
+exec ./k6 x docs --cache-dir $WORK/source-cache --source $WORK/src --version v1.6.x get-started write-your-first-test
+cmp stdout expected.md
+
+-- links/v1.6.x/sections.json --
+{"version":"v1.6.x","sections":[{"slug":"get-started/write-your-first-test","rel_path":"first.md"},{"slug":"get-started/running-k6","rel_path":"running.md"}]}
+-- links/v1.6.x/markdown/first.md --
+Refer to [Running k6](https://grafana.com/docs/k6/<K6_VERSION>/get-started/running-k6/) to learn how to execute your script.
+Use [Visual Studio Code](https://code.visualstudio.com/) to edit it.
+See [details](https://grafana.com/docs/k6/v1.6.1/get-started/running-k6/#results) and [root-relative](/docs/k6/<K6_VERSION>/get-started/running-k6).
+Keep [older docs](https://grafana.com/docs/k6/v1.5.x/get-started/running-k6/), [other docs](https://grafana.com/docs/grafana-cloud/testing/k6/), and [another host](https://example.com/docs/k6/v1.6.x/get-started/running-k6/).
+Keep [section](#results), [docs home](https://grafana.com/docs/k6/<K6_VERSION>/), and [web parentheses](https://en.wikipedia.org/wiki/HAR_(file_format)).
+Image: ![diagram](https://example.com/diagram.png).
+-- links/v1.6.x/markdown/running.md --
+# Running k6
+-- expected.md --
+Refer to Running k6 (`get-started/running-k6`) to learn how to execute your script.
+Use [Visual Studio Code](https://code.visualstudio.com/) to edit it.
+See details (`get-started/running-k6`) and root-relative (`get-started/running-k6`).
+Keep [older docs](https://grafana.com/docs/k6/v1.5.x/get-started/running-k6/), [other docs](https://grafana.com/docs/grafana-cloud/testing/k6/), and [another host](https://example.com/docs/k6/v1.6.x/get-started/running-k6/).
+Keep [section](#results), [docs home](https://grafana.com/docs/k6/v1.6.x/), and [web parentheses](https://en.wikipedia.org/wiki/HAR_(file_format)).
+Image: diagram.
+-- index.md --
+---
+title: Get started
+---