[Feature] asciidoctor: Escape Curly Braces in Validation Text #137
Comments
adambkaplan
added a commit
to adambkaplan/konflux-ci-docs
that referenced
this issue
Feb 27, 2025
Initial attempt to generate reference documentation for Konflux APIs. This adds scripting to generate reference docs for Kubernetes CRDs that are added as part of a Konflux instance. The process utilizes the `crd-ref-docs` tool to generate asciidoc directly from source code. The format of the generated asciidoc can be adjusted by updating the files in the `api-gen/templates` directory, which are Go-based text templates. Refer to the crd-ref-docs codebase for available template functions [1]. Generation of equivalent reference docs for upstream dependencies, such as Tekton, is out of scope for this iteration. Future improvements may consider providing links to upstream sources. Annotations and labels that alter the behavior of upstream APIs are likewise out of scope for this iteration, but can be considered as a future/follow-up improvement. Note - some Enterprise Contract validations contains regex that are not correctly escaped for asciidoc. This is a known issue with crd-ref-docs and requires manual intervention to make `npm run build` happy [2]. [1] https://github.com/elastic/crd-ref-docs [2] elastic/crd-ref-docs#137 Signed-off-by: Adam Kaplan <[email protected]>
adambkaplan
added a commit
to adambkaplan/elastic-crd-ref-docs
that referenced
this issue
Feb 27, 2025
Asciidoc interprets curly braces as an identifier. Kubebuilder validations may contain curly braces as part of a regular expression pattern. This adds an escape character to the leading curly brace when rendering validation content for `asciidoctor`. Per documentation [1], this is sufficient to prevent id attribute interpretation. This change does not broadly add escape characters to all curly braces used in CRD godoc text. This risks breaking teams that have embedded asciidoc within their code comments - for example, to provide links or other cross-references. Fixes elastic#137 [1] https://docs.asciidoctor.org/asciidoc/latest/subs/prevent/#escape-with-backslashes
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Validation text can include regular expressions containing curly braces (
{,}).asciidoctorcan confuse these for an attribute, causing warnings when rendering HTML.Escaping these curly braces can fix this issue.
The text was updated successfully, but these errors were encountered: