Fix markdown links to multi-version CRDs #118
Open
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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>
.I could not find a way to implement this change in a backward-compatible manner for users having custom markdown templating.
Fixes #60