---
title: "Markdown abbreviation keys: what pandoc wrote in a test"
slug: markdown-abbreviations
excerpt: "The section With the abbreviations extension on quotes the HTML and native tree pandoc wrote for a file holding one key line."
quickAnswer: "The section The test file and its key line shows ab.md and the reader settings used. Extension lists and one failed commonmark run are quoted in Which readers list the abbreviations extension. Extension-off output is quoted under The key line under markdown and commonmark, beside spec grep counts. Under With the abbreviations extension on, HTML from two reader settings appears beside one native tree. The section Two keys on adjacent lines quotes a file with stacked keys. A file that puts its key first is covered in A key line above the text. A pointer to raw tags is in Typing an abbr tag by hand. Steps with grep and pandoc fill Find and test abbreviation keys in a file."
keyTakeaways:
  - "Under Which readers list the abbreviations extension, two filtered extension lists and a commonmark error message are quoted."
  - "The section The key line under markdown and commonmark quotes HTML and native output from runs with the extension off."
  - "Pandoc's HTML and native output with the extension on appear in With the abbreviations extension on."
  - "Output for a file holding stacked keys is set out in Two keys on adjacent lines."
  - "Commands that find keys and count tags make up Find and test abbreviation keys in a file."
publishedDate: 2026-10-21
dateModified: 2026-10-21
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: My markdown abbreviation key shows up as text. What happened?
    a: "Runs where the key stayed in the HTML are quoted in The key line under markdown and commonmark."
  - q: Does commonmark accept the abbreviations extension?
    a: "The commonmark extension filter and the error from one run are quoted in Which readers list the abbreviations extension."
  - q: Did pandoc write an abbr element?
    a: "The HTML and native tree pandoc printed with the extension on are quoted in With the abbreviations extension on."
  - q: Can I test an abbreviation key in my file?
    a: "Find-and-count commands sit under Find and test abbreviation keys in a file."
related:
  - markdown-definition-lists
  - raw-html-in-markdown
  - markdown-footnotes
---

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:

```text
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:

```sh
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:

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

```text
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](markdown-definition-lists.md).

## The key line under markdown and commonmark

The command:

```sh
pandoc -f markdown -t html ab.md
```

Output:

```html
<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:

```sh
pandoc -f markdown_phpextra -t html ab.md
```

Output:

```html
<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:

```sh
pandoc -f markdown_phpextra -t native ab.md
```

```text
[ 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:

```text
Jane Doe read the HTML and CSS notes.

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

The plain `markdown` reader wrote this:

```html
<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](raw-html-in-markdown.md).

## 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](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

More at [sashmark.com](https://www.sashmark.com/).