Markdown bullet points: what two pandoc readers wrote

In these tests, pandoc's HTML for identical lines shifted with the reader handed to -f, and in one case with a single pandoc extension.

One Mac ran every conversion below, and its pandoc was 3.8.3. This page sticks to what pandoc printed and says nothing about how any program draws a list. Marker rules, nesting and indent counts belong to the nested list and block quote guide; this page leaves them there.

Three files to test

The test folder holds three short inputs, and an extra script added four more. The output of cat bullets-after-para.md was a sentence with two dash items right beneath it:

Steps for Jane Doe:
- open the file
- check the totals

cat bullets-mixed.md showed three items, and each line uses a different marker:

- open the file
* check the totals
+ send to Jane Doe

For cat bullets-loose.md the output was two items with a gap line splitting them:

- open the file

- check the totals

Every one of these files was converted under -f markdown and again under -f commonmark, both times to html. Each of the four extra files is shown where a section first needs it.

A list right under a sentence

Start with the sentence file and the markdown reader:

pandoc -f markdown -t html bullets-after-para.md

<p>Steps for Jane Doe: - open the file - check the totals</p>

All three lines folded into one <p>. The dashes survived as plain characters inside the text, and no <ul> came out. Each line break inside that paragraph turned into a single space, so the colon after Doe and the first dash sit one space apart in the output.

Switching to commonmark put a <p> first and a <ul> after it:

pandoc -f commonmark -t html bullets-after-para.md

<p>Steps for Jane Doe:</p>
<ul>
<li>open the file</li>
<li>check the totals</li>
</ul>

Spec lines 4887 to 4889 back this run: in CommonMark, a list may break into a paragraph, and the two need no gap line.

For this case pandoc offers lists_without_preceding_blankline, which is a pandoc extension. Pandoc prints one list of extensions per reader; on the markdown one, line 38 is -lists_without_preceding_blankline, so the markdown reader starts with it switched off. No line in the commonmark list names it; the extra script searched that list and got a count of 0, while the same search on the markdown list found line 38. With a plus and the extension name added after markdown, the result changed:

pandoc -f markdown+lists_without_preceding_blankline -t html bullets-after-para.md

<p>Steps for Jane Doe:</p>
<ul>
<li>open the file</li>
<li>check the totals</li>
</ul>

Those five lines match the commonmark run above, tag for tag.

A second fix puts a gap line beneath the sentence. The extra script saved that version as bullets-after-para-fixed.md, and cat printed it like this:

Steps for Jane Doe:

- open the file
- check the totals

Under plain -f markdown, and again under plain -f commonmark, the output matched the five lines quoted above: one <p>, then a <ul> holding two items. No extension was needed once the gap was there. Ordered items under a sentence have their own condition, which the post on numbered lists works through.

Switching between dash, star and plus

The mixed-marker file gave two different shapes. First the markdown run:

pandoc -f markdown -t html bullets-mixed.md

<ul>
<li>open the file</li>
<li>check the totals</li>
<li>send to Jane Doe</li>
</ul>

Then the commonmark run:

pandoc -f commonmark -t html bullets-mixed.md

<ul>
<li>open the file</li>
</ul>
<ul>
<li>check the totals</li>
</ul>
<ul>
<li>send to Jane Doe</li>
</ul>

The item text came out identical in both runs. What changed was how the three <li> lines were grouped into <ul> blocks.

Under commonmark the switch started a new list at each marker change, as the Markdown cheat sheet says, while the markdown reader kept all three items in one list. The commonmark result matches spec line 4857, which says a switch of bullet character opens a fresh list, and lines 4838 to 4841, which treat two bullet markers as the same type only when they use the same character.

The extra script also ran this file under markdown+lists_without_preceding_blankline. That gave one <ul> holding three items, matching plain markdown, so for this file the output stayed put.

To keep one list under both readers, the extra script wrote bullets-one-marker.md with a dash on each line:

- open the file
- check the totals
- send to Jane Doe

Both -f markdown and -f commonmark turned that file into one <ul> with three <li> lines inside.

A blank line between two items

Both readers got the same command shape:

pandoc -f markdown -t html bullets-loose.md
pandoc -f commonmark -t html bullets-loose.md

Each printed these four lines:

<ul>
<li><p>open the file</p></li>
<li><p>check the totals</p></li>
</ul>

Every item's text sat inside a <p> that sat inside its <li>. For a contrast, the extra script ran bullets-tight.md, which holds the same two items with no gap between them. Under both readers that file gave <li>open the file</li> and <li>check the totals</li>, with no <p> tags at all.

Line 4851 of the spec calls a list with blank lines between its items loose. The nesting guide named in the intro goes further into loose and tight lists, so this section stops at the output.

Bullets that start with a number

A bullet item can hold text that begins with digits. The extra script wrote bullets-number-text.md:

- 12 invoices for Doe Holdings
- 3 receipts for John Doe

Both readers printed the same HTML:

pandoc -f commonmark -t html bullets-number-text.md

<ul>
<li>12 invoices for Doe Holdings</li>
<li>3 receipts for John Doe</li>
</ul>

The digits stayed as text inside each <li>. Pandoc wrote a <ul> and no <ol> for this file under either reader. The markdown run sits in the extra log, and its four lines of HTML matched the ones above character for character.

Checking a list with grep

The extra script carried out these steps, with the test files in its working folder. To test your own list, swap your file in for the mixed-marker one.

1. Show the file using cat bullets-mixed.md. Check which character leads each item line. Here the three lines began with -, * and +.
2. Convert it under one reader and save the result: pandoc -f markdown -t html bullets-mixed.md -o bullets-mixed-markdown.html.
3. Count the list openings with grep -c '<ul>' bullets-mixed-markdown.html. Here the count was 1.
4. Repeat step 2 with the other reader: pandoc -f commonmark -t html bullets-mixed.md -o bullets-mixed-commonmark.html.
5. Count its list openings: grep -c '<ul>' bullets-mixed-commonmark.html. This count came back 3.
6. Count items in each saved file. Both grep -c '<li>' bullets-mixed-markdown.html and grep -c '<li>' bullets-mixed-commonmark.html printed 3.

Equal item counts beside different <ul> counts show that the readers kept the same items and grouped them in different ways. A <ul> count above 1 for a list you meant as one is a sign to check the markers.

Top lines that begin with % bring up a separate question about what pandoc takes as a title, and the sibling post on the markdown document title reports those runs.

Where Sashmark fits

The Sashmark build aims to let you type a correction into the displayed text itself. Its Round-Trip goal is strict: each line you leave untouched would be written back to disk exactly as it was. Changes View belongs to the same plan, and it would mark what is new since your prior look, needing no git repo.

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.