githubmarkdownpandoccommonmark

What is the correct way to use a pipe (|) in an inline code block in a table in Markdown?


In a table in Markdown, a pipe character (|) is used to separate columns in a table. However, it's also a pretty common character in code, especially as the bitwise OR operator. When writing inline code blocks in a Markdown table, how should the pipe be escaped, if at all?

There are two candidate methods for writing a pipe in a literal.

This is accepted and rendered correctly by Pandoc and StackOverflow, but not by GitHub:

| My Table!          |
| ------------------ |
| behold, a pipe: `|`|

This is accepted and rendered correctly by GitHub, but not by Pandoc or StackOverflow:

| My Table!           |
| ------------------- |
| behold, a pipe: `\|`|

It seems to be unclear as to whether the pipe needs to be escaped. Does the Markdown specification describe whether the pipe must be escaped?


Solution

  • There is no "correct" way because Markdown has no standard or official specification and its original creator rejected efforts to standardize it or write a spec(1, 2). It turned into an ugly fight. The end result was the balkanization of Markdown.

    But the world is converging around CommonMark as standard. Even GitHub Flavored Markdown (GFM) is now a superset of CommonMark.

    Pandoc, btw, supports multiple variants of Markdown. You should be able to force it to work the same as GitHub.

    StackOverflow is supposed to use CommonMark (one of its founders, Jeff Atwood, was one of the lead people behind CommonMark). But since CommonMark doesn't include table syntax, it looks SO's implementation deviated from GitHub's.