Map plain URLs to docs URLs

[shainaraskas]

To leverage docs link validation, mapping all links introduced in godoc comments to docs-builder style xlinks with link text. We warn on "plain" docs links so this will also make any docs build output cleaner.

Wired it into hack/api-docs/build.sh so url-mapping.json is applied to the rendered markdown after crd-ref-docs runs, and warns on any unmapped URL

Regenerated main.md and applied link changes to docs that were generated for previous cloud-on-k8s releases

[prodsecmachine]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[pkoutsovasilis]

Suggested change

	| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: [Configure APM Server](docs-content://solutions/observability/apm/apm-server/configure.md) |
	| *`config`* __[Config](#config)__ | Config holds the APM Server configuration. See: [Configure APM Server](docs-content://solutions/observability/apm/apm-server/configure) |

I think the .md isn't correct here, this applies to many links altered in this PR

[pkoutsovasilis]

hmmm I just saw the build.sh and url-mapping.json changes. I find it way less cumbersome to add a link without the .md here compared to the mapping approach. Any reason we shouldn't just remove the .md?

[shainaraskas]

the .md is valid for cross-repo docs links. the cross-repo link syntax helps us to validate that the link targets are still present in the docs system. plain links will also throw warnings in docs CI.

the reason why I'm mapping them rather than just editing the strings in the go files is because the go files also build the CRDs, and I expect that in some cases where the CRD content is surfaced, they'd just print as plain text: [Configure APM Server](https://www.elastic.co/docs/solutions/observability/apm/apm-server/configure). we'd also still run into the plain link warning in this case.

[pkoutsovasilis]

ok then maybe it's worth investigating another more dynamic way of mapping the link, for example replace docs-content:// with https://www.elastic.co/docs/ and remove/add accordingly the .md suffix. To be honest the current url-mapping.json feels too cumbersome to me

[shainaraskas]

these docs haven't changed meaningfully since 3.0. I don't think we'd have a lot to maintain here.

Unfortunately, the xref syntax is unique per repository, and we'd have to teach the mapper what patterns belong to which repos. This is the lightest weight solution I could think of that gets the links into the right shape.

We can close this for now and leave the links plain, but I'd have to revisit this if our linking validation became more restrictive in the docs tooling.

[github-actions]

🔍 Preview links for changed docs

• docs/reference/api-reference/3_0_0.md
• docs/reference/api-reference/3_1_0.md
• docs/reference/api-reference/3_2_0.md
• docs/reference/api-reference/3_3_0.md
• docs/reference/api-reference/3_3_1.md
• docs/reference/api-reference/3_3_2.md
• docs/reference/api-reference/3_4_0.md
• docs/reference/api-reference/main.md

[github-actions]

Vale Linting Results

Summary: 28 warnings, 13 suggestions found

⚠️ Warnings (28)

File	Line	Rule	Message
docs/reference/api-reference/3_0_0.md	205	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_0_0.md	1723	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_0_0.md	1772	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_0_0.md	1953	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_1_0.md	205	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_1_0.md	1723	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_1_0.md	1772	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_1_0.md	1953	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_2_0.md	205	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_2_0.md	1723	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_2_0.md	1772	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_2_0.md	1953	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_0.md	207	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_0.md	1790	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_0.md	1839	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_0.md	2020	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_1.md	207	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_1.md	1791	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_1.md	1840	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_1.md	2021	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_2.md	207	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_2.md	1791	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_2.md	1840	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_3_2.md	2021	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_4_0.md	207	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_4_0.md	1883	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_4_0.md	1932	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.
docs/reference/api-reference/3_4_0.md	2113	Elastic.BritishSpellings	Use American English spelling 'customization' instead of British English 'customisation'.

💡 Suggestions (13)

File	Line	Rule	Message
docs/reference/api-reference/3_1_0.md	92	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.
docs/reference/api-reference/3_1_0.md	95	Elastic.Repetition	"to" is repeated.
docs/reference/api-reference/3_2_0.md	92	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.
docs/reference/api-reference/3_2_0.md	95	Elastic.Repetition	"to" is repeated.
docs/reference/api-reference/3_3_0.md	94	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.
docs/reference/api-reference/3_3_0.md	97	Elastic.Repetition	"to" is repeated.
docs/reference/api-reference/3_3_1.md	94	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.
docs/reference/api-reference/3_3_1.md	97	Elastic.Repetition	"to" is repeated.
docs/reference/api-reference/3_3_2.md	94	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.
docs/reference/api-reference/3_3_2.md	97	Elastic.Repetition	"to" is repeated.
docs/reference/api-reference/3_4_0.md	94	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.
docs/reference/api-reference/3_4_0.md	97	Elastic.Repetition	"to" is repeated.
docs/reference/api-reference/main.md	95	Elastic.WordChoice	Consider using 'open' instead of 'launch', unless the term is in the UI.

---

The Vale linter checks documentation changes against the Elastic Docs style guide.

To use Vale locally or report issues, refer to Elastic style guide for Vale.

[barkbay]

Thanks for the change, I understand the value of the link validation improvement. One thing I'm wondering about is the inline Python script in build.sh, I'd rather keep the build tooling in Go if possible.

Since https://github.com/elastic/crd-ref-docs is our own fork, would it be feasible to add URL mapping support there instead? renderer/markdown.go already does string substitution on doc text, so it could be one place to apply a URL mapping loaded from the tool's config. That would let us drop the Python post-processing step entirely and make the feature available to other teams using the tool.

[shainaraskas]

thanks, @barkbay. I've upleveled the mapping support to the generator in elastic/crd-ref-docs#199. Would you be the right person to review it?