Add code fencing example in the style guidlines

[DanyC97]

This PR should bring more clarity on the code fencing style guidelines.

[netlify]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit c348a8e

https://deploy-preview-12783--kubernetes-io-master-staging.netlify.com

[netlify]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit a444f1a

https://deploy-preview-12783--kubernetes-io-master-staging.netlify.com

[netlify]

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 8bbf749

https://deploy-preview-12783--kubernetes-io-master-staging.netlify.com

[DanyC97]

/assign @Bradamant3

[DanyC97]

just a note to let people know that the shell code fencing was used instead of bash because of the below stats taken from en lang

~kubernetes/website/content/en/docs:align-on-shell-style*]# grep -R "\`\`\`bash" * | wc -l
     144

vs

kubernetes/website/content/en/docs:align-on-shell-style*]# grep -R "\`\`\`shell" * | wc -l
    1534

[sftim]

This seems confusing. What should I use for code written for a POSIX shell? What about for code that specifically expects bash?

[DanyC97]

What about for code that specifically expects bash?

do you have an example for that ?

[makocchi-git]

@DanyC97

I have a question about code fencing style.
What code style should I use for the command output?

---

example (using "^" instead of "`")

^^^shell
kubectl get pods
^^^

^^^???
NAME READY STATUS RESTARTS AGE
sample 1/1 Running 0 15m
^^^

---

shell or nothing?

[sftim]

@makocchi-git I asked a similar question as part of #12739
I think we don't have an answer yet.

[DanyC97]

^^^shell
kubectl get pods
^^^

^^^???
NAME READY STATUS RESTARTS AGE
sample 1/1 Running 0 15m
^^^

@makocchi-git i could be missing s'thing here, why a command output can't be formatted like "```" ?
Now in the code i've seen people been using "```none" but imo that is not covered by hugo nor Linguist so i'm also confused.

Maybe the reviewers can chime in and clarify a bit but imo using backtick instead of "^^^" is better

[makocchi-git]

@sftim Thank you. I watch and follow #12739.

[Bradamant3]

/hold

Thanks for the PR and for all the related discussions in the related issue and PR.

But can you say a bit more about why we need this PR and especially the enforcement of it (which I see others offering in related PRs)? We don't have syntax highlighting in the docs output for snippets in different languages, so this isn't something that affects the visible usability of the docs, and it's hard to imagine enforcing compliance going forward.

We've tried pretty hard to keep the style guide simple, and compliance is already an ongoing point of discussion. So I'm concerned about adding complexity when the UX value isn't clear.

(In any case, this wouldn't be the right place for the proposed recommendations -- the section that's added to is about inline code formatting, not about fenced code blocks.)

[DanyC97]

@Bradamant3 thank you for taking the time to review it

But can you say a bit more about why we need this PR and especially the enforcement of it (which I see others offering in related PRs)?

For someone new to the code base it could be very confusing to pick the option:

• is it "```bash" or any alias they feel it should be used - "```shell", "```sh" etc
• is it "```go" or "```golang"
• is it "```yaml" or "```yml"

You can argue that everyone can use whatever they want but i thought that since there is a style guide then whoever is reviewing the PR will be aware of it and will try to enforce it

We don't have syntax highlighting in the docs output for snippets in different languages, so this isn't something that affects the visible usability of the docs, and it's hard to imagine enforcing compliance going forward.

I agree it doesn't add value from user perspective (ie - business value if i can use this term) however from code/ developer perspective i personally believe there is some value - see above. Also i personally like to keep code clear/ clean

So I'm concerned about adding complexity when the UX value isn't clear.

okay, fair point

(In any case, this wouldn't be the right place for the proposed recommendations -- the section that's added to is about inline code formatting, not about fenced code blocks.)

i used this section because in the guide it says

For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`)

There is no specific section for code fencing however i'm happy to change it - just let me know your preference

[steveperry-53]

@DanyC97 Thank you for the PR. All, thanks for the discussion.

All things considered, I recommend keeping it simple: just use a triple backtick, and don't try to specify what kind of code it is. Based on my experience with this doc set, I don't think authors and reviewers will go to the trouble of making sure every code snippet has the proper language or shell label. Given that the labels have no effect on the rendered pages, I don't see the point in working toward making the docs adhere to this more specific form of labeling code snippets.

[sftim]

@steveperry-53 I'm not sure I've understood what you're saying here, specifically:

I don't think authors and reviewers will go to the trouble of making sure every code snippet has the proper language or shell label. Given that the labels have no effect on the rendered pages, I don't see the point in working toward making the docs adhere to this more specific form of labeling code snippets.

I see that https://kubernetes.io/docs/reference/kubectl/cheatsheet/#bash renders with highlighting, and that's something I find useful. It sounds like you might be saying that the highlighting there doesn't happen, or maybe that all code blocks are highlighted using the same rules whatever way they are labelled.
Can you clarify?

[DanyC97]

in addition to what @sftim said, let me add my comments @steveperry-53

just use a triple backtick, and don't try to specify what kind of code it is.

if that is the case (although i do love coloring like @sftim already mentioned) fine but i'd like to see consistency across the board. i.e - strip all md files to adhere to this new rule if that is the case

I don't think authors and reviewers will go to the trouble of making sure every code snippet has the proper language or shell label.

happy to be the picky person in order to help with the compliance and keep the docs aligned with the guidelines

that the labels have no effect on the rendered pages

if that is the case then how come other pages do show some differences ?I'm aware of a page which use a custom shortcode but everyone else doesn't and nobody is using the built in hugo highlights shortcode

[steveperry-53]

@DanyC97, Maybe I'm wrong about not getting highlighting differences. @Bradamant3, do you know whether the labels on code fences make any difference in the rendered snippets?

[Bradamant3]

Thanks @zacharysarah for the clear and sensible summary.

@steveperry-53 I haven't seen other examples like the ones that sftim and Zach point to -- I think it's fair to say they're not common. I also thought I'd seen plenty of examples marked as shell that don't render like the example Zach pointed to, but quite possibly I'm mistaken. But that's really a side note.

[DanyC97]

thank you all for taking the time to review and provide your input, much appreciated.
I'll re-do the PR and then i can move on with the rest.

@zacharysarah regarding

We need to avoid binary thinking about consistency. We don't need to require language-specific code fencing for all examples, nor should we remove all language-specific fencing for sheer consistency's sake

fair point, thank you 👍

[DanyC97]

@zacharysarah pls help review

[DanyC97]

@zacharysarah maybe for another PR i think we can (if you agree) standardize on the guidelines expressed here

And in that way we can kill 2 birds with 1 stone:

• the output and how we do it today - see here which is bit too much if you ask me (nothing wrong with the PR though which follows the guidelines)
• and consistency around sh/shell/bash etc

[zacharysarah]

@DanyC97 Some more feedback.

[zacharysarah]

Make sure to end the sentence with a period. It's also helpful to specify what this is related to.

{{< note >}}
The website supports syntax highlighting for code samples, but specifying a language isn't required. For example, you can enable highlighting for Python samples by enclosing the sample like so: 
<code>```py
import foo
```</code>.
{{< /note >}}

[DanyC97]

feedback taken, thanks.

just added the word ,is optional

[DanyC97]

@zacharysarah let me know if anything else is missing

[DanyC97]

/sig docs

[zacharysarah]

@DanyC97 One final nit. Let's use this wording instead:

The website supports syntax highlighting for code samples, but specifying a language is optional.

Otherwise LGTM 👍

[DanyC97]

done @zacharysarah

[zacharysarah]

@DanyC97 Be sure to remember the period at the end. 😉

[zacharysarah]

/hold cancel

[zacharysarah]

/lgtm
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: zacharysarah

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:

• content/en/OWNERS [zacharysarah]

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