Closed tengqm closed 3 years ago
[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
This comment follows on from https://github.com/kubernetes-sigs/reference-docs/issues/256#issuecomment-939453430:
In https://github.com/kubernetes/website/pull/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.
@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
@tengqm: Closed this PR.
Mabye a shortcode can produce the same warning, by checking t
auto_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.
closes: #256