Fix markdown links to multi-version CRDs

[antonincms]

Implementation

This PR fixes links to multi-version CRDs by adding a reference to the version in the anchor and the link.

Approach

I considered implementing links in pure Markdown, like #### v1.Embedded1, but preferred to use HTML links instead, like #### <a id="github-com-elastic-crd-ref-docs-api-v1-embedded1">Embedded1</a>. This approach is closer to what is done in Asciidoc and the final result seems more readable to me (especially in multigroup APIs where it would look like #### mygroupname-v2alpha1.Embedded1). I guess supporting both methods could be an option, but it would require two functions to render links, and users would need to know how to adjust their templating accordingly.

This change will also break existing links in custom Markdown templates, as it now uses GroupVersionID to link to resources. To fix this, replace ## {{ $gv.GroupVersionString }} in gv_details.tpl with ## <a id="{{ markdownGroupVersionID $gv | markdownSafeID }}">{{ $gv.GroupVersionString }}</a>.

As explained in #60 I could not find a way to implement this change in a backward-compatible manner for users having custom markdown templating, except by introducing a new function like markdownRenderHTMLTypeLink. However, I wanted to get feedback before implementing this approach because:

• the current rendering method is broken for multiversion APIs
• crd-ref-docs is still in v0.x.y so I think we could tolerate breaking custom templates for markdown
• this change would align Markdown output more closely with AsciiDoc

Fixes #60

[cla-checker-service]

💚 CLA has been signed

[antonincms]

Hello @thbkrkr,

I hope you don’t mind me pinging you directly, I saw that you were an active contributor on this repo, and in the absence of any comment on this PR for more than a year I’m wondering if it might have gone unnoticed.

I understand that this kind of change might not be a priority especially from outside of Elastic, but it would be great to have some feedback about it, I’ve been using it at work without issues for a while now, and there’s been some positive feedback from others too (see related issue #60).

Happy to tweak things or provide more context if needed, thanks !

[barkbay]

I'm trying to understand what we are breaking here. IIUC there are at least two breaking changes:

1. Template API — markdownRenderLocalLink goes from one argument to two (link, text). Custom templates that still call it with one argument will fail at render time with a "wrong number of args" error.

2. GV anchor format — Group-version section anchors change from the old slug (e.g. #agentk8selasticcov1alpha1) to the new one (e.g. #agent-k8s-elastic-co-v1alpha1). Any existing link that pointed at the old anchor will no longer match.

My concern with the second one is that it's a silent breaking change: the tool still runs, the docs are generated, and there's no error or warning. The only thing that breaks is existing links that point at those section anchors, from another doc (or maybe the same one?), a README, a bookmark... Users might not notice until something 404s or a "link to API section" stops working, and they may not "connect" that to upgrading crd-ref-docs.

Do you think it's worth breaking these links, or would you consider keeping the legacy GV anchor format for backward compatibility?

[antonincms]

My concern with the second one is that it's a silent breaking change: the tool still runs, the docs are generated, and there's no error or warning. The only thing that breaks is existing links that point at those section anchors, from another doc (or maybe the same one?), a README, a bookmark... Users might not notice until something 404s or a "link to API section" stops working, and they may not "connect" that to upgrading crd-ref-docs.

Maybe you have an example I haven’t thought of, but I have the impression that external links would still work: in the test/expected.md file, both #guestbookspec and #github-com-elastic-crd-ref-docs-api-v1-guestbookspec lead to the type. But links inside the doc itself would be broken.

Do you think it's worth breaking these links, or would you consider keeping the legacy GV anchor format for backward compatibility?

For the Template API (since for external links I don't think it is an issue) I think making these backward compatible is possible, but it would introduce additional complexity, either in the logic, configuration or template coherency between asciidoc and markdown.

Here is two alternatives I see if you really do not want to break existing templates :

One potential solution could be to introduce a field in the configuration, such as templatingVersion, which could accept values like v1alpha1 for the current implementation and v1alpha2 for the fixed version. But for the default value, we would need to decide between two options: either shipping a partially broken version as the default or introducing a breaking change by default but providing an easy way to opt out.

Another alternative that would not break anything short term but would not be great long term could be to introduce a new function, and make new templates use it while keeping existing templates working. The old one could be deprecated and removed eventually, but you'll end up having to explain that markdown and asciidoc templating should use different functions.

[edited to add the second alternative and clarify my point]

[barkbay]

Maybe you have an example I haven’t thought of

In the ECK repo: https://github.com/elastic/cloud-on-k8s/blob/35a72a90c83f3578729480214c9613bdc425e7b1/docs/reference/api-reference/main.md?plain=1

diff --git a/docs/reference/api-reference/main.md b/docs/reference/api-reference/main.md
index 3ea19880e..80bb0c36a 100644
--- a/docs/reference/api-reference/main.md
+++ b/docs/reference/api-reference/main.md
@@ -11,25 +11,25 @@ applies_to:
 # {{eck}} API Reference for main [k8s-api-reference-main]
 
 ## Packages
-* [agent.k8s.elastic.co/v1alpha1](#agentk8selasticcov1alpha1)
-* [apm.k8s.elastic.co/v1](#apmk8selasticcov1)
-* [apm.k8s.elastic.co/v1beta1](#apmk8selasticcov1beta1)
-* [autoops.k8s.elastic.co/v1alpha1](#autoopsk8selasticcov1alpha1)
-* [autoscaling.k8s.elastic.co/v1alpha1](#autoscalingk8selasticcov1alpha1)
-* [beat.k8s.elastic.co/v1beta1](#beatk8selasticcov1beta1)
-* [common.k8s.elastic.co/v1](#commonk8selasticcov1)
-* [common.k8s.elastic.co/v1alpha1](#commonk8selasticcov1alpha1)
-* [common.k8s.elastic.co/v1beta1](#commonk8selasticcov1beta1)
-* [elasticsearch.k8s.elastic.co/v1](#elasticsearchk8selasticcov1)
-* [elasticsearch.k8s.elastic.co/v1beta1](#elasticsearchk8selasticcov1beta1)
-* [enterprisesearch.k8s.elastic.co/v1](#enterprisesearchk8selasticcov1)
-* [enterprisesearch.k8s.elastic.co/v1beta1](#enterprisesearchk8selasticcov1beta1)
-* [kibana.k8s.elastic.co/v1](#kibanak8selasticcov1)
-* [kibana.k8s.elastic.co/v1beta1](#kibanak8selasticcov1beta1)
-* [logstash.k8s.elastic.co/v1alpha1](#logstashk8selasticcov1alpha1)
-* [maps.k8s.elastic.co/v1alpha1](#mapsk8selasticcov1alpha1)
-* [packageregistry.k8s.elastic.co/v1alpha1](#packageregistryk8selasticcov1alpha1)
-* [stackconfigpolicy.k8s.elastic.co/v1alpha1](#stackconfigpolicyk8selasticcov1alpha1)
+* [agent.k8s.elastic.co/v1alpha1](#agent-k8s-elastic-co-v1alpha1)
+* [apm.k8s.elastic.co/v1](#apm-k8s-elastic-co-v1)
+* [apm.k8s.elastic.co/v1beta1](#apm-k8s-elastic-co-v1beta1)
+* [autoops.k8s.elastic.co/v1alpha1](#autoops-k8s-elastic-co-v1alpha1)
+* [autoscaling.k8s.elastic.co/v1alpha1](#autoscaling-k8s-elastic-co-v1alpha1)
+* [beat.k8s.elastic.co/v1beta1](#beat-k8s-elastic-co-v1beta1)
+* [common.k8s.elastic.co/v1](#common-k8s-elastic-co-v1)
+* [common.k8s.elastic.co/v1alpha1](#common-k8s-elastic-co-v1alpha1)
+* [common.k8s.elastic.co/v1beta1](#common-k8s-elastic-co-v1beta1)
+* [elasticsearch.k8s.elastic.co/v1](#elasticsearch-k8s-elastic-co-v1)
+* [elasticsearch.k8s.elastic.co/v1beta1](#elasticsearch-k8s-elastic-co-v1beta1)
+* [enterprisesearch.k8s.elastic.co/v1](#enterprisesearch-k8s-elastic-co-v1)
+* [enterprisesearch.k8s.elastic.co/v1beta1](#enterprisesearch-k8s-elastic-co-v1beta1)
+* [kibana.k8s.elastic.co/v1](#kibana-k8s-elastic-co-v1)
+* [kibana.k8s.elastic.co/v1beta1](#kibana-k8s-elastic-co-v1beta1)
+* [logstash.k8s.elastic.co/v1alpha1](#logstash-k8s-elastic-co-v1alpha1)
+* [maps.k8s.elastic.co/v1alpha1](#maps-k8s-elastic-co-v1alpha1)
+* [packageregistry.k8s.elastic.co/v1alpha1](#packageregistry-k8s-elastic-co-v1alpha1)
+* [stackconfigpolicy.k8s.elastic.co/v1alpha1](#stackconfigpolicy-k8s-elastic-co-v1alpha1)

The link generated by the templates are no longer valid.

The fix is here: elastic/cloud-on-k8s@1fbf718

[antonincms]

In the project you're linking to, I see that _{{ markdownRenderType .Type }}_ generate links like __[ApmServerSpec](#github-com-elastic-cloud-on-k8s-v3-pkg-apis-apm-v1-apmserverspec)__. However, in my case, it generates links like _[GuestbookSpec](#guestbookspec)_, like in crd-ref-doc test/expected.md.
How does the template in the linked project manage to generate fully qualified links like that ? If this is doable, perhaps I’ve missed something, and I could simplify my changes.

The link generated by the templates are no longer valid.

External links would still be valid, but yes, you would need to update your template here.

Since this part is probably unnecessary (packages already contain the group name and version, it only makes links consistent between packages and types), I will change this back.