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?
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.
Related
Is there a standard or convention for embedding metadata in a Markdown formatted post, such as the publication date or post author for conditional rendering by the renderer?
Looks like this Yaml metadata format might be it.
There are all kinds of strategies, e.g. an accompanying file mypost.meta.edn, but I'm hoping to keep it all in one file.
There are two common formats that look very similar but are actually different in some very specific ways. And a third which is very different.
YAML Front Matter
The Jekyll static site generator popularized YAML front matter which is deliminated by YAML section markers. Yes, the dashes are actually part of the YAML syntax. And the metadata is defined using any valid YAML syntax. Here is an example from the Jekyll docs:
---
layout: post
title: Blogging Like a Hacker
---
Note that YAML front matter is not parsed by the Markdown parser, but is removed prior to parsing by Jekyll (or whatever tool you're using) and could actually be used to request a different parser than the default Markdown parser for that page (I don't recall if Jekyll does that, but I have seen some tools which do).
MultiMarkdown Metadata
The older and simpler MultiMarkdown Metadata is actually incorporated into a few Markdown parsers. While it has more recently been updated to optionally support YAML deliminators, traditionally, the metadata ends and the Markdown document begins upon the first blank line (if the first line was blank, then no metadata). And while the syntax looks very similar to YAML, only key-value pairs are supported with no implied types. Here is an example from the MultiMarkdown docs:
Title: A Sample MultiMarkdown Document
Author: Fletcher T. Penney
Date: February 9, 2011
Comment: This is a comment intended to demonstrate
metadata that spans multiple lines, yet
is treated as a single value.
CSS: http://example.com/standard.css
The MultiMarkdown parser includes a bunch of additional options which are unique to that parser, but the key-value metadata is used across multiple parsers. Unfortunately, I have never seen any two which behaved exactly the same. Without the Markdown rules defining such a format everyone has done their own slightly different interpretation resulting in a lot of variety.
The one thing that is more common is the support for YAML deliminators and basic key-value definitions.
Pandoc Title Block
For completeness there is also the Pandoc Title Block. If has a very different syntax and is not easily confused with the other two. To my knowledge, it is only supported by Pandoc (if enabled), and it only supports three types of data: title, author, and date. Here is an example from the Pandoc documentation:
% title
% author(s) (separated by semicolons)
% date
Note that Pandoc Title Blocks are one of two style supported by Pandoc. Pandoc also supports YAML Metadata as described above.
A workaround use standard syntax and compatible with all other viewers.
I was also looking for a way to add application specific metadata to markdown files while make sure the existing viewers such as vscode and github page will ignore added metadata. Also to use extended markdown syntax is not a good idea because I want to make sure my files can be rendered correctly on different viewers.
So here is my solution: at beginning of markdown file, use following syntax to add metadata:
[_metadata_:author]:- "daveying"
[_metadata_:tags]:- "markdown metadata"
This is the standard syntax for link references, and they will not be rendered while your application can extract these data out.
The - after : is just a placeholder for url, I don't use url as value because you cannot have space in urls, but I have scenarios require array values.
Most Markdown renderers seem to support this YAML format for metadata at the top of the file:
---
layout: post
published-on: 1 January 2000
title: Blogging Like a Boss
---
Content goes here.
The most consistent form of metadata that I've found for Markdown is actually HTML meta tags, since most Markdown interpreters recognize HTML tags and will not render meta tags, meaning that metadata can be stored in a way that will not show up in rendered HTML.
<title>Hello World</title>
<meta name="description" content="The quick brown fox jumped over the lazy dog.">
<meta name="author" content="John Smith">
## Heading
Markdown content begins here
You can try this in something like GitHub Gist or StackEdit.
Correct.
Use the yaml front matter key-value syntax — like MultiMarkdown supports — but (ab)use the official markdown URL syntax to add your metadata.
… my workaround looks like this:
---
[//]: # (Title: My Awesome Title)
[//]: # (Author: Alan Smithee)
[//]: # (Date: 2018-04-27)
[//]: # (Comment: This is my awesome comment. Oh yah.)
[//]: # (Tags: #foo, #bar)
[//]: # (CSS: https://path-to-css)
---
Put this block at the top of your .md doc, with no blank line between the top of the doc and the first ---.
Your fake yaml won't be included when you render to HTML, etc. … it only appears in the .md.
You can also use this technique for adding comments in the body of a markdown doc.
This is not a standard way, but works with Markdown Extra.
I wanted something that worked in the parser, but also didn't leave any clutter when I browse the files on Bitbucket where I store the files.
So I use Abbreviations from the Markdown Extra syntax.
*[blog-date]: 2018-04-27
*[blog-tags]: foo,bar
then I parse them with regexp:
^\*\[blog-date\]:\s*(.+)\s*$
As long as I don't write the exact keywords in the text, they leave no trace. So use some prefix obscure enough to hide them.
I haven't seen this mentioned elsewhere here or in various blogs discussing the subject, but in a project for my personal website, I've decided to use a simple JSON object at the top of each markdown file to store metadata. It's a little more cumbersome to type compared to some of the more textual formats above, but it's super easy to parse. Basically I just do a regex such as ^\s*({.*?})\s*(.*)$ (with the s option on to treat . as \n) to capture the json and markdown content, then parse the json with the language's standard method. It allows pretty easily for arbitrary meta fields.
I've got a table in Emacs org-mode, and the contents are regular expressions. I can't seem to figure out how to escape a literal pipe-character (|) that's part of a regex though, so it's interpreted as a table-cell separator. Could someone point me to some help? Thanks.
Update: I'm also looking for escapes for a slash (/), so that it doesn't trigger the start of an italic/emphasis sequence. I experimented with \/ and \// - for example, suppose I want the literal text /foo/ in a table cell. Here are 3 ways of attempting it:
| /foo/ | \/foo/ | \//foo/ |
In LaTeX export, that becomes:
\emph{foo} & \/foo/ & \//foo/
So none of them is the plain /foo/ I'm hoping for.
\vert for the pipe.
Forward slashes seem to work fine for me unescaped when exporting both to HTML and PDF.
Use a broken-bar character, “¦”, Unicode 00A6 BROKEN BAR. This may or may not work for your specific needs, but it’s a good visual approximation.
You could also format the relevant text as verbatim or code:
Text in the code and verbatim string is not processed for Org mode
specific syntax; it is exported verbatim.
So you might try something like =foo | bar= (code) or foo ~|~ bar (verbatim). It does change the output format, though.
I would like to add the following to a bitbucket wiki:
Key | Description |Default |
:-----------|:----------------------------------------------|:--------------|
env |Execution context {development|test|production}|development |
Markdown has a backslash escape for many characters, but not pipe (|). I saw one solution using {development|test|production} but this does not work as you can't use html in bitbucket markdown.
Has anyone found a way to include the pipe character in cell contents in a markdown table on bitbucket?
Bitbucket's Markdown might not support HTML, but it does support Unicode. Inside table cells you can use another character that looks like the pipe character, e.g. ⎮ (0x23AE, INTEGRAL EXTENSION):
Key | Description |Default |
:-----------|:----------------------------------------------|:--------------|
env |Execution context {development⎮test⎮production}|development |
This character won't trigger Bitbucket's Markdown table syntax.
I would like to emphasise several single letters at the beginning of a word to highlight the letters used for an abbreviation. Here's an example in markdown:
*SO* stands for *S*tack *O*verflow
But instead of the expected output (note the slanted first letters S and O) of:
SO stands for Stack Overflow
on Github the output looks like:
SO stands for *S*tack *O*verflow.
Any ideas why is it not emphasised on Github? Does this relate to the different markdown implementations?
Any ideas why is it not emphasised on Github?
This looks to be on purpose. This limit is hinted in their documentation.
Note: The documentation deals with underscores (_), which are similar to stars (*) in markdown
Indeed, the following is not processed by GitHub
*H*yper*t*ext *T*ransfer *P*rotocol
Does this relate to the different markdown implementations?
Well, at least it is documented. Keep in mind that is rightfully named "Github Flavoured Markdown" ;-)
I've got a table in Emacs org-mode, and the contents are regular expressions. I can't seem to figure out how to escape a literal pipe-character (|) that's part of a regex though, so it's interpreted as a table-cell separator. Could someone point me to some help? Thanks.
Update: I'm also looking for escapes for a slash (/), so that it doesn't trigger the start of an italic/emphasis sequence. I experimented with \/ and \// - for example, suppose I want the literal text /foo/ in a table cell. Here are 3 ways of attempting it:
| /foo/ | \/foo/ | \//foo/ |
In LaTeX export, that becomes:
\emph{foo} & \/foo/ & \//foo/
So none of them is the plain /foo/ I'm hoping for.
\vert for the pipe.
Forward slashes seem to work fine for me unescaped when exporting both to HTML and PDF.
Use a broken-bar character, “¦”, Unicode 00A6 BROKEN BAR. This may or may not work for your specific needs, but it’s a good visual approximation.
You could also format the relevant text as verbatim or code:
Text in the code and verbatim string is not processed for Org mode
specific syntax; it is exported verbatim.
So you might try something like =foo | bar= (code) or foo ~|~ bar (verbatim). It does change the output format, though.