Markdown alphabetical list: letters and roman numerals

You want steps labeled a, b and c, or i, ii and iii, in a Markdown file. You type a. to open a line, and what comes out depends on which reader handles the file.

In one test on macOS with pandoc version 3.8.3, a markdown alphabetical list, a roman-numeral list and a few corner cases went through several reader settings. Every result below lists the file and the reader flag, so a rerun is easy. The checks stop at pandoc's HTML output; no viewer was tested.

Letters and roman numerals in the CommonMark spec

Number markers, start numbers and the two delimiters are covered in the numbered list guide. This section asks a narrower thing: do the 0.31.2 rules allow anything besides digits as a marker?

Its wording says digits. Lines 3810 and 3811 define an ordered list marker as a sequence of 1 to 9 arabic digits. Searching that file with case ignored found roman on 0 lines, lowercase letter on 0 lines and alphabetic on 0 lines. As a control, ordered list turned up on 14 lines under that search.

Pandoc adds letters and roman numerals through its fancy_lists extension. In the listing that pandoc --list-extensions=markdown printed, the matching lines were +example_lists, +fancy_lists and +startnum. The pandoc --list-extensions=commonmark listing showed -fancy_lists and had no line for startnum or example_lists.

Lettered lists with the fancy_lists extension

The test file list-alpha.md holds two lines:

a. Open the file
b. Save it

The markdown reader, run as pandoc -f markdown -t html list-alpha.md, printed:

<ol type="a">
<li>Open the file</li>
<li>Save it</li>
</ol>

Four reader settings, four results:

• That list came from the markdown reader.
• pandoc -f commonmark+fancy_lists -t html list-alpha.md gave the same <ol type="a"> list.
• pandoc -f commonmark -t html list-alpha.md returned <p>a. Open the file b. Save it</p>.
• Removing the extension in pandoc -f markdown-fancy_lists -t html list-alpha.md gave that same one-paragraph line.

The letters stayed out of the item text. Pandoc wrote the letter style as a type attribute and kept just the words inside each <li>. In the two runs that lacked it, the second line joined the first, and both markers printed as text.

Roman numerals and a closing parenthesis

The file list-roman.md uses i. and ii.. A second file, list-upper-paren.md, uses capital letters with a closing parenthesis, A) and B).

• In the markdown reader, list-roman.md became <ol type="i"> and list-upper-paren.md became <ol type="A">, with two items in both lists.
• commonmark+fancy_lists gave those same two type values.
• Plain commonmark returned <p>i. Open the file ii. Save it</p> and <p>A) Upper one B) Upper two</p>.
• markdown-fancy_lists printed those same two paragraphs.

The <ol type="A"> tag carried no sign of the ) delimiter that the source used.

A capital letter and a period

In these runs, swapping the parenthesis for a period made the spacing after the marker matter. The file list-upper-dot.md holds A. Upper one and B. Upper two, with one space after both markers. A copy named list-upper-dot2.md puts two spaces there.

• With one space, markdown, commonmark+fancy_lists and plain commonmark all printed <p>A. Upper one B. Upper two</p>.
• With two spaces, markdown and commonmark+fancy_lists returned <ol type="A"> with two items. Plain commonmark kept the single paragraph.

Capital roman numerals followed the same pattern in this test. The file list-roman-upper.md holds I. Open the file and II. Save it with one space, and those three settings printed <p>I. Open the file II. Save it</p>. Its two-space copy, list-roman-upper2.md, came out as <ol type="I"> from markdown and commonmark+fancy_lists.

The A) file in the roman numeral section had one space after its markers and still turned into a list.

When h and i sit next to each other

A lettered list that reaches i raises a question: letter nine, or roman one? The file list-h-i.md tests it:

h. Eighth step
i. Ninth step

Both markdown and commonmark+fancy_lists returned <ol start="8" type="a"> with two items. The i. line stayed in the lettered list that h. opened, in this run. Plain commonmark printed one paragraph, <p>h. Eighth step i. Ninth step</p>.

Compare the earlier list-roman.md test. There, a list that opened with i. came out as <ol type="i">.

Example lists that keep counting

Pandoc's example_lists extension uses the (@) marker. The test file list-example.md holds two (@) items, a paragraph, then a third:

(@) First example.
(@) Second example.

Some text.

(@) Third example.

Output from the markdown reader:

<ol class="example" type="1">
<li>First example.</li>
<li>Second example.</li>
</ol>
<p>Some text.</p>
<ol start="3" class="example" type="1">
<li>Third example.</li>
</ol>

The count carried past the paragraph, so the second list opened at 3. The other three settings, commonmark+fancy_lists, markdown-fancy_lists and plain commonmark, all printed <p>(@) First example. (@) Second example.</p>, then the paragraph, then <p>(@) Third example.</p>.

A label can go inside the parentheses. In list-example-label.md, the first line is (@good) Jane Doe signs. and a later paragraph says As (@good) shows, one line. The markdown reader built a one-item example list and wrote that paragraph as <p>As (1) shows, one line.</p>. With commonmark+fancy_lists, both lines stayed as text with (@good) intact.

Check a lettered list with pandoc

When letters come out as plain text, test the list by itself in a small file. For a lettered list nested under a numbered step, see the nested list and quote guide.

1. Print the lines with cat list-alpha.md to see the markers as typed.
2. Next, try the plain reader: pandoc -f commonmark -t html list-alpha.md. A single <p> holding the letters means this reader built no list in this test.
3. Count list tags. pandoc -f commonmark -t html list-alpha.md | grep -c '<ol' printed 0. Change the flag to -f commonmark+fancy_lists and the count rose to 1; -f markdown gave 1 as well.
4. Read the type attribute in the output. The values a, A, i and I showed up in these tests. If a capital letter with a period stayed as text, compare your spacing with list-upper-dot2.md.

Where Sashmark fits

For Sashmark, typing changes into the rendered page itself sits in the v1 plan. Those edits are planned to carry a clean Round-Trip, with lines you skip planned to keep their bytes unchanged. Also on that plan: a Changes View to highlight what is different in a file between your readings, with no git needed. 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.

Visit sashmark.com.