doc: quotes are displayed as " in description of kubebuilder markers on CRD Validation page

[tenstad]

What broke? What's expected?

See expanded description of +kubebuilder:default on CRD Validation, which appears to come from controller-tools/pkg/crd/markers/validation.go

The struct should be {policy: "delete"}, not {policy: "delete"}.

[camilamacedo86]

Hi @tenstad,

Thank you for raising it. Yes, the descriptions came from controller-tools project. Therefore, the content:

IN: https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/src/reference/markers/crd-validation.md?plain=1

Then, the implementation which is responsible for generate this documentation can be found in: https://github.com/kubernetes-sigs/kubebuilder/tree/master/docs/book/utils/markerdocs

Also, see: https://github.com/kubernetes-sigs/kubebuilder/blob/master/docs/book/markerdocs.sh

So, in order to address the issue described here is required to change its implementation in order to properly handle ".

I will mark as help wanted and it might also be a good first issue. However, is required be able to analyse the code to know how properly change it out. Either is possible to verify the change in the doc preview which is available for each PR done against master, see;

[typeid]

Would be interested in picking up this issue, if that's okay :)

[typeid]

/assign

[typeid]

I believe the issue is the following:

• we are using markerdocs as mdBook preprocessor to generate most of our References section (e.g. CRD Validation)
• this preprocessor writes HTML but the text fields also contain markdown (e.g. this line)
• we call html.EscapeString() on the output of the preprocessor (see here)
• the preprocessed output is then parsed as markdown by mdBook

Basically, the issue doesn't seem to be the quotation marks, but the backticks. mdBook handles the content as raw strings (code block) and doesn't unescape the quotation marks.

1. Raw text:

 object: `{policy: "delete"}`

2. Preprocessor wraps it with HTML in escaped format

object: `{policy: "delete"}`

3. mdBook picks up on the markdown backticks and further wraps it in the according HTML without interpreting the escaped characters:

<code class="hljs">{policy: &#34;delete&#34;}</code>

I'm not yet sure how to move forward with this.
One possibility might be to modify the writeHTML function to not call html.EscapeString on the parts of the string that are between backticks.

[camilamacedo86]

It seems fixed so I am closing this one.
Feel free to re-open if you see a need for it.