Write guidelines of use of`$` in bash/console commands

[ncclementi]

In our docs we have multiple places where we have $ in front of a bash command and in others we don't. When present it's not copied when either selecting and using the copy to clipboard shortcut. But the $ will cause problems in multi line commands. This was fixed across the docs I believe, but we should write this as a guideline for future reference.

I would prefer we don't use it at all for simplicity, but this is a problem when we have a one liner with an output. For example:

```bash
$ echo $PATH
/some/path
```

In our docs, when you copy the cell above, you'll get only the one line that has $.

The one thing it's not clear is when we use console and when we use bash or if it doesn't matter. Ideally we should be consistent too.

TODO:

• Decide weather to use $ only having one liners and displaying the output, or not use it and modify across the docs
• Determine when we use console vs bash and if they are the same, choose one for consistency
• Write guidelines in the README under the "Writing" section.

[jacobtomlinson]

You should use them if you're using the console highlighting (for commands and output) and not if you're using the bash highlighting (commands without output). Although not many folks know about this and often get things mixed up.

With console it highlights the line with the $ as bash and the following lines as text. The copy/paste button also intelligently only copies the bash section after the $ and not the example output (although GitHub's doesn't seem to).

```console
$ ls -ld ~/D*
drwxr-xr-x 2 jtomlinson jtomlinson 4096 Oct 21  2022 Desktop
drwxr-xr-x 3 jtomlinson jtomlinson 4096 Nov 15  2022 Documents
drwxr-xr-x 4 jtomlinson jtomlinson 4096 Oct  2 14:44 Downloads
```

If you're including a bunch of bash lines without any output examples then you should just use bash and not include the $.

```bash
for VARIABLE in file1 file2 file3
do
    echo "hello world"
done
```

[ncclementi]

You should use them if you're using the console highlighting (for commands and output) and not if you're using the bash highlighting (commands without output). Although not many folks know about this and often get things mixed up.

I notice multiple places were we have one liners that look like this,

```console
$ gcloud init
```

are we saying in this case we should do?

```bash
gcloud init
```

With console it highlights the line with the $ as bash and the following lines as text

This only seems to happen at the markdown level, for example I see it here:

deployment/source/guides/colocate-workers.md

Lines 39 to 47 in 0032104

	```console
	$ kubectl get po -A --watch | grep nvidia
	kube-system nvidia-driver-installer-6zwcn 1/1 Running 0 8m47s
	kube-system nvidia-driver-installer-8zmmn 1/1 Running 0 8m47s
	kube-system nvidia-driver-installer-mjkb8 1/1 Running 0 8m47s
	kube-system nvidia-gpu-device-plugin-5ffkm 1/1 Running 0 13m
	kube-system nvidia-gpu-device-plugin-d599s 1/1 Running 0 13m
	kube-system nvidia-gpu-device-plugin-jrgjh 1/1 Running 0 13m
	```

But in the rendering this it looks like this, is it supposed to have a different highlight in the rendering?

[jacobtomlinson]

I notice multiple places were we have one liners that look like this

In theory yes that should be bash and not use the $. If there are cases like that we should fix them. However, if there are a whole load of console examples and one of them is a one-liner it might be weird to have one bash mixed into a bunch of console blocks.

is it supposed to have a different highlight in the rendering?

I think the rendering of the bash on the top line is not very exciting, we could probably tweak the highlighter settings in our docs to make it nicer. If you look at the source the bash has been highlighted and the text hasn't. You can also see that the pipe has a different CSS class to the other words, so it could be a different colour like it is in the GitHub view. Our style just sets them to the same colour for some reason.

The key thing there though is if you click the little copy button in the corner it only copies kubectl get po -A --watch | grep nvidia.