As a software developer, when I'm learning a new language, framework, or tool, more of my time is spent reading documentation than actually writing something. Many doc renderers like GitHub Markup, mdBook, or Jekyll make the experience great for everyone. Documentation authors get to write in Markdown and readers get to consume it like a web page.

One very convenient feature of many Markdown renderers is a little "copy" button in the top right corner of code blocks. It automatically copies the code to your clipboard so you can quickly paste it in your terminal or code editor. Here's an example of some code blocks in GitHub with the wonderful copy button.

Some sites (like Whtwnd apparently) do not include a copy button, which is unfortunate but it's not a huge deal. I can still easily triple click to select the whole line and copy it. Try it yourself.

npm install -D typescript

The problem

Markdown is amazing and it makes everyone's lives easier. But it's only as convenient as the authors choose to make it, and some authors neglect the user experience. Here's an example of what not to do, in my opinion.

(Try to triple click this one too)

$ npm install pino

Authors that want to indicate that a line of code is a command to be run in a terminal will often do that by prepending the command with a $. It looks pretty innocent, you've probably seen dozens of examples of it, and it may as well be industry-standard to include the little $ to communicate a bash command. If you want to know more about why it's a dollar sign, you can read more on this superuser question asked over 15 years ago.

My problem with it is that it completely eliminates the usefulness of the copy button. The dollar sign is included in the text of the code block, meaning it's copyable and selectable. So I also can't triple-click because it'd still select the $ at the front. If I were to paste that text in my terminal, I'd get an error that looks like bash: command not found: $.

The frustrating next step is to press the up arrow in your terminal to recall the previous command, then move the cursor all the way to the left just to delete that ridiculous character. Most terminals do not allow you to use your mouse to move the cursor around, and some terminals don't even allow you skip over whole words by holding Ctrl or Option, depending on your OS. So if you've just pasted a long or multi-line command, you must suffer.

In these situations I could just carefully select only the command I want to copy.

But I'm lazy, and authors could just as easily not include the symbol in the first place. Sites like GitHub have recognized that it's annoying to manually select text in a code block to copy it, so that's why the copy button exists. Catering to the lazy developers is part of the point of docs, tutorials, and quickstart guides.

The solution

The $ only exists to communicate that it's a bash command. There are other ways to communicate this without including the symbol in the code block text.

I've seen some sites that render the code block with an unselectable $. Here's a NextUI code snippet with the $ built into the UI.

This is a fine solution, but unfortunately it isn't very common and it's made with a React component, not standard Markdown.

I think the $ is outdated and it doesn't communicate anything to newer developers anyway. Can we just get rid of it completely?

Yes. CommonMark code blocks allow the author to specify the language of the code using an info string. Most Markdown renderers include syntax highlighting for all the popular languages, you just have to tell it which language. Code blocks are created by surrounding a block of text with a pair of triple backticks (```). After the first pair, you can include the name of the language.

echo Hello World

Some renderers also bake the info string into the code block UI component so there's no ambiguity.

This is my favorite solution. It requires the author to be more precise about what kind of code it is without contaminating the selectable text of the code block. While it's not widely adopted among Markdown renderers yet, it totally could be. It uses a basic syntax feature that nearly every Markdown flavor supports and it makes code easier for readers to consume.

My plea

To Markdown authors

• Always include the language info string on your code blocks. There's no reason not to.
• Stop including $, >, %, #, or any other prompt symbol that a reader wouldn't want to copy.

To Markdown renderer devs

• Add the "copy" button to the code block if you haven't already.
• Include the info string somewhere too.

To readers of Markdown docs

• Keep being lazy.