search

elastic / crd-ref-docs

Generates Kubernetes CRD API reference documentation
Apache License 2.0
100 stars 50 forks source link

Generate unique type headers #30

Open justenstall opened 2 years ago

justenstall commented 2 years ago

The current headers in the markdown template are not guaranteed to be unique since they do not include the version. For my use case I have multiple versions of a CRD with the same types in each version. Since the output is all in one file, when I want to link to a type from another markdown file (like out.md#typename), it will only ever link to the first heading matching the link, which could be an out of date reference. I tried creating my own template for this but the issue is the markdown RenderTypeLink function will no longer create accurate links with the change.

justenstall commented 1 year ago

Workaround for this is to generate each version to its own file, so markdown links are versioned even though the headers do not reference the version. 

crd-ref-docs --source-path=path/to/v1alpha1 --config=apidocs.yaml --renderer=markdown --output-path=docs/apis/v1alpha1.md
crd-ref-docs --source-path=path/to/v1alpha2 --config=apidocs.yaml --renderer=markdown --output-path=docs/apis/v1alpha2.md
crd-ref-docs --source-path=path/to/v1alpha3 --config=apidocs.yaml --renderer=markdown --output-path=docs/apis/v1alpha3.md