Markdown abbreviation keys: what pandoc wrote in a test

If a markdown abbreviation key isn't doing what you expected, first find out which pandoc reader parsed the file. Pandoc's reader settings with the abbreviations extension on dropped the key line from the HTML in this test and wrote no abbr element. The settings without it kept the line as a second paragraph of plain text.

On one Mac, each conversion below happened once, and the pandoc build reported 3.8.3. Spec searches used the CommonMark text at 0.31.2. What you read here is limited to pandoc's HTML and native tree output, and nothing past that output was checked.

The test file and its key line

Running cat ab.md printed:

The HTML spec is long.

*[HTML]: Hyper Text Markup Language

Line 1 is a sentence that uses the short form HTML. Line 3 holds the key: an asterisk, then the short form in square brackets, then a colon, one space and the long form. A blank line sits between them.

Four reader settings turned ab.md into HTML: markdown, markdown_phpextra, markdown+abbreviations and commonmark. One more run used markdown_phpextra with -t native, which prints pandoc's internal document tree in place of HTML. A plus sign after a reader name turns an extension on for that one run.

Which readers list the abbreviations extension

The test filtered two extension lists:

pandoc --list-extensions=markdown | grep -E 'abbreviations|smart|blank_before'
pandoc --list-extensions=markdown_phpextra | grep -E 'abbreviations'

The first printed -abbreviations, +blank_before_blockquote, +blank_before_header and +smart, one per line. The second printed +abbreviations. A minus sign marks an extension that reader can use but leaves off, and a plus sign marks one that is on.

For commonmark, pandoc --list-extensions=commonmark | grep -c abbreviations printed 0. Asking for the extension anyway failed:

pandoc -f commonmark+abbreviations -t html ab.md

The extension abbreviations is not supported for commonmark.
Use --list-extensions=commonmark to list supported extensions.

That run exited with code 23. In pandoc, abbreviation keys come from an extension, as term-and-colon lists do in the post on definition lists.

The key line under markdown and commonmark

The command:

pandoc -f markdown -t html ab.md

Output:

<p>The HTML spec is long.</p>
<p>*[HTML]: Hyper Text Markup Language</p>

Running pandoc -f commonmark -t html ab.md gave those same two lines. With abbreviations off, the key came through as its own paragraph, asterisk and brackets included.

A native run agrees. pandoc -f markdown -t native ab.md printed a tree holding a second Para whose first string is Str "*[HTML]:", followed by the four words of the long form.

Counting with grep -ci in the spec file gave 0 lines for abbreviation and 0 for abbr. The control term link reference definition matched 21 lines.

With the abbreviations extension on

The command:

pandoc -f markdown_phpextra -t html ab.md

Output:

<p>The HTML spec is long.</p>

With -f markdown+abbreviations, pandoc printed that same single line. The key line was gone. Around the word HTML in the sentence, pandoc put no abbr element.

The native run shows this from inside pandoc:

pandoc -f markdown_phpextra -t native ab.md

[ Para
    [ Str "The"
    , Space
    , Str "HTML"
    , Space
    , Str "spec"
    , Space
    , Str "is"
    , Space
    , Str "long."
    ]
]

One Para holds five strings, and the tree carries no node for the abbreviation. The one change this test turned up in the output was the missing key line.

Two keys on adjacent lines

The file ab-two.md holds a sentence with two short forms, then two key lines stacked directly on top of each other:

Jane Doe read the HTML and CSS notes.

*[HTML]: Hyper Text Markup Language
*[CSS]: Cascading Style Sheets

The plain markdown reader wrote this:

<p>Jane Doe read the HTML and CSS notes.</p>
<p><em>[HTML]: Hyper Text Markup Language </em>[CSS]: Cascading Style
Sheets</p>

In that output, the text between the two leading asterisks sits inside an em element, and both asterisks are gone. That em element came from the two stacked keys in this file.

Under markdown+abbreviations and under markdown_phpextra, both keys vanished. The whole output was <p>Jane Doe read the HTML and CSS notes.</p>. The native run for markdown+abbreviations showed one Para with the words of that sentence and no other block.

A key line above the text

The file ab-first.md puts the key on line 1 and the sentence on line 3. Under markdown+abbreviations, pandoc wrote <p>The HTML spec is long.</p>, the same line it wrote for ab.md.

Under plain markdown, the key came out first as its own paragraph, <p>*[HTML]: Hyper Text Markup Language</p>, with the sentence after it. Moving the key above the text made no difference to the HTML from the setting with the extension on.

Typing an abbr tag by hand

None of the runs on this page produced an abbr element. Writing the tag into the file yourself means typing raw HTML, such as <abbr title="Hyper Text Markup Language">HTML</abbr>. No run in this test converted such a line. Raw tags in Markdown get their own walkthrough in the raw HTML post.

Find and test abbreviation keys in a file

Work through these steps if a key line turns up in your HTML, or if a key you wrote seemed to do nothing.

1. Find the key lines. Four lines matched grep -n '^\*\[' ab.md ab-two.md ab-first.md, each prefixed by file and line number.
2. Read the extension list for your reader. pandoc --list-extensions=markdown_phpextra | grep -c abbreviations printed 1, and the same filter on commonmark printed 0.
3. Turn the extension off, convert, and look for the long form. After pandoc -f markdown -t html ab.md -o ab-md.html, grep -c 'Hyper Text' ab-md.html returned 1, so the key text stayed in the HTML.
4. Convert with the extension on and count again. After pandoc -f markdown+abbreviations -t html ab.md -o ab-on.html, the same count on ab-on.html was 0.
5. Count abbr tags. After pandoc -f markdown_phpextra -t html ab.md -o ab-php.html, grep -c '<abbr' ab-php.html printed 0. The control count, grep -c 'HTML spec' ab-php.html, returned 1.
6. Scan for stray em elements. Two keys on adjacent lines under markdown gave one, as the section Two keys on adjacent lines shows.

Where Sashmark fits

Were Sashmark's first version to land the way its plan reads, you might fix a word straight on the displayed page. Then the clean Round-Trip, another planned part, would put the file back so lines left alone keep their old bytes. Further along that list, a Changes View would flag what differs from your prior look at the file, git not required.

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.