Heredoc snippets remove syntax coloring

[MatthewFallon]

Description of Issue

Current page link I am looking at for reference: https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/

This is 100% a tiny gripe and not a priority demand from the documentation, but would make everything more readable for me so I will bring it up.

Heredocs

Heredocs, and a cat command using them, are a great way to make a copypasta tutorial like this extremely predictable and posix compliant. I generally have no issue with the use of them, BUT they make the entire heredoc a flat string when it comes to syntax highlighting.

When looking through the documentation above, I personally prefer to just scan the page for reference while working on a personal tool rather than actually copy paste each individual section in a sandbox just to see the output files, and having each file you are using as an example instead show as just a flat red blob of text rather than useful yaml with syntax highlighting makes it difficult to scan the page or read each document.

Suggestion

I would love if instead the behavior of the docs was to keep the files that are wanted pasted in normally, with syntax highlighting, and then provide a copy button or similar that allows the user to fill their clipboard with the associated heredoc cat command, allowing for the best of both worlds in one view.

Or

Similar to other docs which provide multiple languages with a selector along the top of each code section to keep the same language selection across the page/session providing two separate sections with the heredoc snippets as the default but allowing people to swap to the file based examples. Allowing the best of both worlds while defaulting to the sort of standard copy pasta codelab format.

Obviously know that either of these solutions may be untenable depending on the structure of the docs overall, but figured I would toss it out there, thanks for reading 👍 😄

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.

[niranjandarshann]

/language en
/sig docs

[sftim]

Our (existing) policy is to use downloadable manifests based on code_sample - see https://kubernetes.io/docs/contribute/style/hugo-shortcodes/#source-code-files

We have more work to do to get there. And, we might want to widen the scope of what you can copy; see #45910

Do you have an example of a particular snippet that you think should be done a different way to help learners @MatthewFallon ?

I personally am wary of encouraging people to copy and paste snippets as-is; see #45910 (comment)

[sftim]

/priority backlog
(ie, nothing higher)

[sftim]

/kind feature

[MatthewFallon]

Do you have an example of a particular snippet that you think should be done a different way to help learners @MatthewFallon ?

Hey @sftim 👋 yes looking at this section I see the following code snippet:

# Create a application.properties file
cat <<EOF >application.properties
FOO=Bar
EOF

cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
  files:
  - application.properties
EOF

Which as commands holds no purpose other than:

1. Create text file application.properties with contents
2. Create yaml file kustomization.yaml with contents

There are multiple instances of this on that page, which really only serves the purpose of providing an easy copy paste as manually typing a heredoc command like such is kind of cumbersome to begin with haha.

I think a fair point on not wanting to encourage too much copy pasting using buttons as such 👍 I had figured that was the original intent based on content. In this case I think you're right that these commands would better be shown as two individual code_sample statements instead. I think many of the code snippets on this page just need to be modified to fit that format.

Will leave this here as clarification of the suggestion, and will potentially look into contributing the change myself if I find the time. Thanks for adding context! 👍 😄

[sftim]

We don't use code_sample for shell commands (it's for manifests).

However, you can copy just the FOO=Bar line into a text editor if you want. I get that people might like the computer to do more of the work, but I also think we should focus on our high priority issues ahead of any more work here.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

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-sigs/prow repository.