component-docs icon indicating copy to clipboard operation
component-docs copied to clipboard

Consistent rules for executable code fragments

Open vados-cosmonic opened this issue 7 months ago • 2 comments

After the meeting of SIG Docs today, we landed on what are consistent rules for dealing with syntax highlighting for commands.

While there has been discussion (and there are always opinions!) the principles that are in use at Fermyon seem to be good enough and prevent bikeshedding:

  • console is used only when commands and output are shown
    • $ must be before lines that show commands to show that a shell is being used
  • sh/bash is for commands that should be copy-pastable

While there are many ways this could go, I think standardizing on this usage and encoding it in CONTRIBUTING.md (CONVENTIONS.md?)or some such file is important to move past this quickly and be consistent going forward!

vados-cosmonic avatar Apr 09 '25 19:04 vados-cosmonic