It’s very popular to put a $
on lines that are intended to be a command in code documentation that involves the terminal (i.e. the command line).
Like this:
$ brew install somepackage
The point of that is that it mimics the prompt that you (may) see on your command line. Here’s mine:

So the dollar sign ($
) is a little technique that people use to indicate this line of code is supposed to be run on the command line.
Minor trouble
The trouble with that is that I (and I’ll wager most other people too) will copy and paste commands like that from that documentation.
If I run that command above in my terminal exactly as it’s written…

…it doesn’t work. $
is not a command. How do you deal with this? You just have to know. You just need to have had this problem before and somehow learned that what the documentation is actually telling you is to run the command brew install somepackage
(without the dollar sign) at the command line.
I say minor trouble as there are all sorts of stuff like this in every job in the world. When I put something like font-size: 2.2rem
in a blog post, I don’t also say, “Put that declaration in a ruleset in a CSS file that your HTML file links to.” You just have to know those those things.
Fixing it with CSS
The fact that it’s only minor trouble and that tech is laden with things you just need to know doesn’t mean that we can’t try to fix this and do a little better.
The idea for this post came from this tweet that got way more likes than I thought it would:
To expand on that, I’d expect you’re probably marking up your docs something like:
<p>Install package like:</p>
<pre><code class="command">brew install package</code></pre>
Now you can insert the $ as a pseudo-element rather than as actual text:
code.command::before {
content: "$ ";
}
Now you aren’t just saving yourself a character in the HTML, the $
cannot be selected, because that’s how pseudo-elements work. So now you’re now a bit better in the UX department. Even if the user double-clicks the line or tries to select all of it, they won’t get the $
screwing up the copy-paste.
Hopefully they aren’t equally frustrated by not being able to copy the $
. 😬
So, anyway, something like this incredible design by me:
Fixing it with text
A lot of documentation for code-things are on a public git repo place like GitHub. You don’t have access to CSS to style what GitHub looks like, so while there is trickery available, you can’t just plop a line of CSS in there to style things.
We might have to (gasp) use our words:
<p>
Install the package by entering this
command at your terminal:
</p>
<kbd class="command">brew install package</kbd>
Other thoughts
- You probably wouldn’t bother syntax highlighting it at all. I don’t think I’ve ever seen a terminal that syntax highlights commands as you enter them.
- Eric Meyer suggested the
<kbd>
element which is the Keyboard Input element. I like that. I’ve long used<code>
but I think<kbd>
is more appropriate here. - Tim Chase suggested using a
<span>
and including the prompt in the HTML so you can style it uniquely if you want, including making it not selectable withuser-select: none;
. - Justin Searls has a dotfiles trick where if you accidently copy/paste the
$
, it just ignores it and runs everything after it. - Jackson Bates suggests being very careful about what you copy and paste to a terminal.
- I learned that
$
is also a way of denoting “unprivileged” commands while # is for root commands. Part of that reason is that if you copy-paste a root command, it won’t run as it will be recognized as a comment.
That’s what the $ is representing, I was wondering for years now. On my windows PC I never saw any sort of $. Thanks for clearing that up.
The dollar sign in command means that the command is ran as a normal user.
If the command is ran by an administrator (typically “root”), the sign is #
Hello, great post as usual. The $ prompt not only tells you that the following is something you should run in a terminal, but that the command should be run as a normal user. If you have to run the command with superuser privileges then the command is preceded with a # prompt. So I think this should be taken into account when doing this.
yess
some thoughts on your other thoughts:
I know of one shell with syntax highlighting: it’s called fish and it’s pretty neat, although it’s scripts are not compatible with bash / sh
At least on Linux, bash is usually configured to replace the $ prompt with a # if logged in as root
Wow this is pure genious! Would be great to see it implemented on the forums and in documentation on git pages.
For so many years, I was afraid of the terminal; any time I’d try and run a command —
$
not found would literally haunt me. I was never sure if running the command without it would mean the same thing or would cause the hell to break loose.Now I teach CLI Automation; I love writing scripts to automate grunt work. I wish I had started sooner than I did.
To this day, I believe that adding a
$
makes it more difficult for beginners to get used to the idea of the command line. It’s not beginner-friendly—the missing context.I’d encourage developers to use text to explain the commands and make them more accessible than using a
$
to denote one.And thank you, Chris, for writing about this. A CSS trick like this definitely helps.
PowerShell does a kind of syntax highlighting. It’s useful, to some extent.
By the way, shouldn’t the example be inside
<pre><kbd>
?I’m pretty sure I have asked this on some Stack Exchange network, but unfortunately I cannot find it. If I remember correctly, one answer suggested that the reason to print
$
in a code example is to actually prevent people from copying a bunch of lines to paste them in their terminal, to make it harder to run into an undesired outcome.I’d say that zsh-syntax-highlighting (coupled with zsh-autosuggestions) changed my life forever… :P
The
fish
shell and Powershell have built-in syntax highlighting.