73

I am writing some documentation in markdown and I want to document how to create a text file using a bash HEREDOC. Here is the command I want to document:

# cat > /tmp/answers.txt <<EOT
> value1=blah
> value2=something else
> value3=`hostname`
> value4=onetwothree
EOT

In markdown one uses the ` to render the text as "code" I have tried doing this ...

`# cat > /tmp/answers.txt <<EOT`
`> value1=blah`
`> value2=something else`
`> value3=\`hostname\``
`> value4=onetwothree`
`EOT`

... but that results in something that looks like this ...

# cat > /tmp/answers.txt <<EOT
> value1=blah
> value2=something else
> value3=\

hostname
> value4=onetwothree
EOT

phuclv
  • 37,963
  • 15
  • 156
  • 475
Red Cricket
  • 9,762
  • 21
  • 81
  • 166

4 Answers4

103

The original Markdown syntax documentation covers this; it says that you have to use multiple backticks to bracket the code expression, so like this:

``here you go - ` this was a backtick``

renders like this:

here you go - ` this was a backtick

If you want to include a backtick in normal text, not in a code block, a backslash escape does the trick; for example this:

Here's a backtick: \`; then, here's another one: \`

renders like this:

Here's a backtick: `; then, here's another one: `

As a commenter asked, “How can I have a code expression that contains only a backtick, or a sequence of multiple backticks?”

A single backtick can be written inline like this: `` ` ``

which, as you can see, renders like this: `

The rules is, if you want to write a sequence of backticks, the enclosing backticks (which must be written without whitespace between them) must be a different number of backticks from the quoted backticks. It does not have to be a greater number, only a different number. For example, seven backticks can be written like this: ` ``````` `

which then renders like so: ```````

Any number of consecutive backticks may be used as a code block delimiter. For example, an alternate form of the single backtick would be this: `````````` ` ``````````

which renders like so: `

(I tested this on commonmark and github and it behaves the same so it's not just a Stack Overflow oddity)

Glyph
  • 31,152
  • 11
  • 87
  • 129
  • This was helpful to me, but I'd also add to your instructions that your line can't end with three backticks. E.g. I was trying to surround ``eval `ssh-agent -s` `` with pairs of double backticks and eventually realized that I needed to add a space before the closing pair of backticks. – Ryan Jul 01 '18 at 14:58
  • 2
    I think you should also add that you can have a single space after the first `` and before the final one too, to allow escaping multiple backticks. – geekley Jul 10 '18 at 15:46
  • How to render 
    `(func)
    in a code block?     – tejasvi88 Mar 19 '21 at 13:30
  • I can't show this in a comment, because in comments you can't use triple-backticks. But the answer above, "use double backticks around the `
    `" will work fine.
     – Glyph Mar 21 '21 at 01:21
  • Thanks @geekley. I was trying to style a code one-liner that included two backticks, with the second at the very end of the expression. The double-backtick trick didn't work on GitHub without spaces inside the double-backticks. As you say, the spaces need to be balanced so the space character doesn't get rendered. – jdunning Jan 22 '22 at 20:58
  • How can I have a code expression that contains **only** a backtick, or a sequence of multiple backticks? – Karl Knechtel Aug 28 '22 at 06:05
  • @KarlKnechtel I've expanded the answer to cover this clarification. – Glyph Sep 10 '22 at 00:05
16

This code block below does the trick.

```
# cat > /tmp/answers.txt <<EOT
> value1=blah
> value2=something else
> value3=`hostname`
> value4=onetwothree
EOT
```

The three Backtick means it's snippet of code and a snippet must end with three more Backtick.

For more help with Markdown refer this CheatSheet.

Adi
  • 5,560
  • 1
  • 24
  • 37
10

I think you need to change the "delimiter" from a single back tick to a double...

i.e.: ``value3=\`hostname\` ``

should render

> value3=\`hostname\`

Robert Ekendahl
  • 277
  • 2
  • 11
  • 1
    Thanks for the reply but that didn't solve my problem. I think I'll go with `> value3=$(hostname)` and give up on using old school backticks in my scripts. – Red Cricket Jun 19 '14 at 18:03
  • @RedCricket: I updated my commented with better formatting. Not sure if that will help you but you can use as many back ticks as you need to start/end a line. If you use 3 (for example) then 1 or 2 back ticks are rendered correctly. I think your solution will work as well – Robert Ekendahl Jun 19 '14 at 18:25
  • 1
    @RobertEkendahl this worked for me. I think the general solution to the problem is that if you want to use back-ticks inside the code block, you can't fence it with single back ticks. you need double or triple. Thanks! –  Apr 06 '15 at 15:48
3

Addendum: At least on SO, when the code starts or ends with `, you need to add spaces inside of backticks on both sides.

That is, if you want foo`, you must spell it as `` foo` ``, not as ``foo` ``, because the latter incorrectly renders as foo` .

At most one whitespace is removed in this manner (from each side), so ` foo ` renders as foo .

HolyBlackCat
  • 78,603
  • 9
  • 131
  • 207
  • 1
    Thank you. This answer helped me the most because my string ended with a backtick and I didn't want that extra space. – Mayron Mar 26 '23 at 11:07