Markdown blockquote attribution: three pandoc tests

A markdown blockquote attribution is the line under a quote that names the speaker. Typed three ways, one name line gave three results in this test. Two hyphens became one character or stayed put, depending on the reader setting. One hyphen started a list, and a raw cite element passed through as typed.

One macOS machine ran each setting once, and its copy of pandoc carried version number 3.8.3. What follows is the text and markup pandoc produced, and no claim here reaches past it.

Four quote files and four reader settings

Running grep -n '' qa.md qa-list.md qa-cite.md qa-esc.md printed:

qa.md:1:> Ship the small fix first.
qa.md:2:>
qa.md:3:> -- Jane Doe
qa-list.md:1:> Ship the small fix first.
qa-list.md:2:>
qa-list.md:3:> - Jane Doe
qa-cite.md:1:> Ship the small fix first.
qa-cite.md:2:>
qa-cite.md:3:> <cite>Jane Doe</cite>
qa-esc.md:1:> Ship the small fix first.
qa-esc.md:2:>
qa-esc.md:3:> \- Jane Doe

Lines 1 and 2 match across the four files. Line 3 is where they part ways: two hyphens and a space in qa.md, one hyphen and a space in qa-list.md, a cite element in qa-cite.md, and a backslash ahead of one hyphen in qa-esc.md. That last file came from an extra test written for this post.

Each file went through pandoc -t html with four -f values: markdown, markdown-smart, commonmark and commonmark+smart. Filtering the extension lists printed +smart for the markdown reader and -smart for commonmark. So smart was on for two of the four settings, markdown and commonmark+smart, and off for the other two.

Two hyphens before the name

The command:

pandoc -f markdown -t html qa.md

Output, ASCII-normalized. The text inside the third line's <p> element opens with one character, code point U+2013, shown here as [U+2013]:

<blockquote>
<p>Ship the small fix first.</p>
<p>[U+2013] Jane Doe</p>
</blockquote>

Pandoc swapped the two hyphens for a single character. To find out which, this test sent the same conversion through od:

pandoc -f markdown -t html qa.md | od -An -tx1

Output:

           3c  62  6c  6f  63  6b  71  75  6f  74  65  3e  0a  3c  70  3e
           53  68  69  70  20  74  68  65  20  73  6d  61  6c  6c  20  66
           69  78  20  66  69  72  73  74  2e  3c  2f  70  3e  0a  3c  70
           3e  e2  80  93  20  4a  61  6e  65  20  44  6f  65  3c  2f  70
           3e  0a  3c  2f  62  6c  6f  63  6b  71  75  6f  74  65  3e  0a

On the fourth row, right after 3e (the > that closes the opening p tag), sit the three bytes e2, 80 and 93. Decoded as UTF-8, those three bytes give code point U+2013. Next comes 20, a space, and then 4a for the J in Jane. The commonmark+smart run wrote the same third line.

Both runs that had smart switched off, markdown-smart and commonmark, kept the hyphens as typed:

<blockquote>
<p>Ship the small fix first.</p>
<p>-- Jane Doe</p>
</blockquote>

What the smart extension does to hyphens and dots in general is laid out in the dashes section of the smart quotes walkthrough. For a name line, the one fact this test needs from it is the swap: with smart on, two hyphens came out as U+2013 here.

To keep the hyphen pair, the runs quoted here point to a reader setting with smart off. To get U+2013 instead, markdown and commonmark+smart each wrote it in this test.

A single hyphen starts a list

The file qa-list.md drops one of the two hyphens. Under all four settings, pandoc wrote:

<blockquote>
<p>Ship the small fix first.</p>
<ul>
<li>Jane Doe</li>
</ul>
</blockquote>

The name became the lone item of a bullet list, sitting inside the quote. Spec lines 3808-3809 (CommonMark 0.31.2) name - as one of three bullet list markers, and its list item rule on lines 3817-3822 builds an item from a marker followed by a space and some text.

Lists and quotes placed inside one another follow their own rules, which the nesting walkthrough for quotes and lists covers.

Escaping the hyphen with a backslash

The extra file qa-esc.md keeps one hyphen and sets a backslash in front. Under all four settings, pandoc wrote:

<blockquote>
<p>Ship the small fix first.</p>
<p>- Jane Doe</p>
</blockquote>

The backslash dropped out of the output, the hyphen stayed as plain text, and the name stayed in a paragraph. Counting list item tags in the written files backs this up. Under markdown, grep -c '<li>' printed 1 for the qa-list.md output and 0 for the qa-esc.md output.

So a hyphen you want kept as text, with no list, came through here once a backslash sat before it.

A cite tag kept as raw HTML

The file qa-cite.md types the name inside a <cite> element. Under all four settings, pandoc wrote:

<blockquote>
<p>Ship the small fix first.</p>
<p><cite>Jane Doe</cite></p>
</blockquote>

Apart from the p element around it, nothing on that line changed. The tag and the name passed through untouched, and smart made no change to them in either state.

For raw tags in Markdown more broadly, see the guide to HTML typed into Markdown.

Attribution syntax in the spec

The > that opens each line of the four test files is the block quote marker defined on spec lines 3416-3420.

This test found no attribution syntax in the spec. Run on the spec file, grep -ci -F for attribution matched 1 line, line 13, and that line belongs to the license notice. For cite, that search matched 0 lines. The term block quote, kept as a control, came back with 57 lines.

Test a name line of your own

These commands back the steps below, and each one ran in this test:

grep -n '' qa.md qa-list.md qa-cite.md qa-esc.md
od -An -tx1 qa.md
pandoc -f markdown -t html qa-list.md -o qa-list.html
grep -c '<li>' qa-list.html
pandoc -f markdown -t html qa-esc.md -o qa-esc.html
grep -c '<li>' qa-esc.html
pandoc -f commonmark -t html qa.md -o qa.html
grep -c -- '--' qa.html
pandoc -f markdown -t html qa.md -o qa.html
grep -c -- '--' qa.html
pandoc -f markdown -t html qa.md | od -An -tx1

When a quote's name line came out wrong, try these six steps.

1. Print the quoted lines with numbers. The grep -n '' command listed line 3 of each file, as quoted under Four quote files and four reader settings.
2. Read the source bytes on the name line. Running od on qa.md showed 2d 2d 20 just before 4a: two hyphens and a space, then the J.
3. Count list items in the HTML. For the qa-list.md output, grep -c '<li>' printed 1, and on the qa-esc.md output it printed 0.
4. Count hyphen pairs left in the HTML. After the commonmark run on qa.md, the -- count was 1. After the markdown run on that file, it was 0.
5. Check the bytes pandoc wrote. The last command showed e2 80 93 where the two hyphens had been.
6. Pick the form for your name line. Two hyphens gave U+2013 with smart on and -- with it off in this test. A backslash before one hyphen kept the name in a paragraph, and a cite element passed through as typed.

Where Sashmark fits

Suppose Sashmark's v1 turns out as mapped. A reader could then retouch a phrase while viewing the formatted text, and a planned piece called clean Round-Trip would store every line nobody touched with its bytes intact. Mapped for that version as well: a Changes View that could signal each revision since the reader's earlier pass, with no git step.

It is in development and has not been released. The app itself has no AI features. See the planned features, the help pages and the roadmap for where each part stands.

More at sashmark.com.