Revise the callout for generated component references

[tengqm]

closes: #256

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tengqm

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [tengqm]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[sftim]

This comment follows on from #256 (comment):

In kubernetes/website#29877 I change the “edit this page” link to highlight some new advice about third party content. See https://k8s.io/docs/setup/production-environment/container-runtimes/ for an example (needs a wide enough viewport).

We already hide the “edit this page” link for autogenerated content. Rather than omit it entirely, we could perhaps at least include a link to the in-page advice about the page being autogenerated.

So long as these generated pages are marked as auto_generated in their front matter, we can use a Hugo layout to:

• add a pageinfo block (I'd put it at the end of the page, but it could go at the top) saying that the content is auto generated
• mark the “edit this page” link with a similar link

Overall, I'd prefer not to put the customisation in the generator. We can add a single shortcode eg {{% auto_generated_content_warning %}} (which potentially helps with localization), or we can rely on Hugo's layout concept to let us achieve the same thing without any shortcode at all. I think that's a better way to separate the concerns. For example: the generator then doesn't have to track any change to Docsy or to our custom shortcodes that relates to this notice.

If you like, marking pages as auto_generated: true is model, and the Hugo layout is view (or possibly view-model).

Another thing I'd consider is using the blockade plugin to Prow to automatically tell submitters that they are changing generated content. Updates outside of a release are rare, and the release docs team have access (AIUI) to remove the labels that blockade sets.

I hope I've convinced you @tengqm about that other approach. If you like to see an example before deciding, I can do that too.

[tengqm]

@sftim Alright, using a shortcode looks a better option. I'm not sure if we need to inject anything from the generator side. Mabye a shortcode can produce the same warning, by checking tauto_geneated: true.

/close

[k8s-ci-robot]

@tengqm: Closed this PR.

In response to this:

@sftim Alright, using a shortcode looks a better option. I'm not sure if we need to inject anything from the generator side. Mabye a shortcode can produce the same warning, by checking tauto_geneated: true.

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[sftim]

Mabye a shortcode can produce the same warning, by checking tauto_geneated: true.

You can do that with a Hugo layout, which works a lot like a shortcode but doesn't require any change to the page source.
I'll aim to propose a PR that implements something along the lines of what I suggested.