Markdown font size: headings, spans and pandoc tests

You want one line in a Markdown file to print larger than the lines around it, and there's no key for that. So you reach for a heading, a tag, or a styled span, and then you check what the HTML holds.

To see what markdown font size markup turns into, every test here ran once on macOS, with pandoc at 3.8.3. Covered: heading levels, tags typed by hand, size styles set in bracketed spans, and a small caps class. Every quoted output names its test file for a rerun. Checks here stop at pandoc's HTML; nothing in this post tests how a viewer draws that HTML.

Font size in plain CommonMark

Font size gets no markup of its own from CommonMark; the version checked was 0.31.2. A grep over the spec file, ignoring case, found font-size on 0 lines and font size on 0 lines. The terms smallcaps and small caps also came back 0. A whole-word search for size also matched nothing: 0 lines.

The word font matched 1 line: line 2234, where basefont sits in the spec's list of HTML block tag names (lines 2233 to 2242). For a control, heading matched 67 lines in that search.

So the spec gives you two things to work with: heading levels and raw HTML. Pandoc adds a third through its bracketed_spans extension. In this test's extension listing, the commonmark reader showed -bracketed_spans and +raw_html, and the markdown reader showed +bracketed_spans and +raw_html. The next sections test each route.

Heading levels from one to six

Spec section 4.2 sets the heading level from the count of # characters at the start, one through six (lines 1043 to 1053). Example 62 (lines 1056 to 1070) maps # to <h1> and ###### to <h6>.

The test file fs-headings.md:

# Jane Doe

###### Jane Doe

Output by reader:

• pandoc -f commonmark -t html fs-headings.md returned <h1>Jane Doe</h1> and <h6>Jane Doe</h6>.
• pandoc -f markdown -t html fs-headings.md returned <h1 id="jane-doe">Jane Doe</h1> and <h6 id="jane-doe-1">Jane Doe</h6>. This reader added an id to both headings.

Neither output holds a font-size declaration. The tag name carries the level, and apart from the id from the markdown reader, no attribute appears in either output. Use a heading where a new part of the document starts. Headings carry structure; size alone does not.

A seventh hash sign doesn't buy a smaller heading. The spec says more than six # characters is not a heading (line 1072). In an added test, fs-x-seven.md held ####### Jane Doe. Output from commonmark was <p>####### Jane Doe</p>, a plain paragraph with the hash signs kept. Pandoc's markdown reader gave back <p class="heading" id="jane-doe">Jane Doe</p>, also a paragraph, this time with a class.

One more added test put a size span inside a heading. The file fs-x-heading-span.md:

# [Jane Doe]{style="font-size: 2em"}

With markdown, pandoc returned <h1 id="jane-doe"><span style="font-size: 2em">Jane Doe</span></h1>. With commonmark, it returned <h1>[Jane Doe]{style="font-size: 2em"}</h1>, with the braces printed inside the heading.

Full heading syntax, plus links that jump to a heading, is in the heading syntax write-up.

Typed span, small and big tags

How pandoc treats typed HTML in general is covered in the typed-HTML write-up. This section tests the size tags alone.

One line made up the file fs-span-html.md:

<span style="font-size: 2em">Jane Doe</span>

For that file, commonmark and markdown both gave this line: <p><span style="font-size: 2em">Jane Doe</span></p>. The tag and its style attribute came out as typed, inside a paragraph.

The file fs-small.md tried the two size tags:

<small>Jane Doe</small> and <big>Doe</big>

Both readers returned <p><small>Jane Doe</small> and <big>Doe</big></p>. Pandoc kept both tags in place within one paragraph.

Bracketed spans that set a size

With bracketed_spans, the words go in square brackets and the attributes follow straight on in curly braces.

The test file fs-span.md:

[Jane Doe]{style="font-size: 2em"}

Three reader settings gave three results:

• pandoc -f commonmark -t html fs-span.md gave back <p>[Jane Doe]{style="font-size: 2em"}</p>. Nothing became a span; the markup printed as typed.
• pandoc -f commonmark+bracketed_spans -t html fs-span.md returned <p><span style="font-size: 2em">Jane Doe</span></p>.
• pandoc -f markdown -t html fs-span.md returned that same span, with no extension named on the command line.

Both span results match the output from the typed tag in fs-span-html.md, character for character. So the bracket route and the typed route ended at the same HTML here: a span carrying a style attribute. How that attribute displays was outside this test.

For color set with this bracket form, see the text color tests.

Small caps with a class

One more span class gets a section here: smallcaps. The test file fs-smallcaps.md:

[Jane Doe]{.smallcaps}

Results by reader setting:

• pandoc -f markdown -t html fs-smallcaps.md returned <p><span class="smallcaps">Jane Doe</span></p>.
• pandoc -f commonmark+bracketed_spans -t html fs-smallcaps.md, from the added tests, returned that same span.
• pandoc -f commonmark -t html fs-smallcaps.md, also from the added tests, returned <p>[Jane Doe]{.smallcaps}</p>, braces included.

The output span carries a class and no style attribute in this test.

Test a size line in pandoc

When a size you typed seems to be missing, run that one line through pandoc by itself.

1. Put the line alone in a new file.
2. Then convert: pandoc -f commonmark -t html. When square brackets and curly braces still appear in the output, the reader built no span in this test.
3. Rerun with -f markdown, or keep the commonmark reader and add the extension: -f commonmark+bracketed_spans.
4. Use grep to count matches. As a sample, pandoc -f markdown -t html fs-span.md | grep -c 'font-size' printed 1. Then pandoc -f commonmark -t html fs-span.md | grep -c '<span' gave 0, and the commonmark+bracketed_spans run of that count gave 1.
5. Count heading tags the same way. pandoc -f commonmark -t html fs-headings.md | grep -c '<h' printed 2 for the two headings in the file.
6. If a count comes back 0, check your line against the three results under Bracketed spans that set a size.

Where Sashmark fits

Under the v1 plan, the app is being built to let the rendered page itself take your edits, with a Round-Trip planned to stay clean and untouched lines planned to come back with their exact bytes. For tracking edits, the plan names a Changes View that is planned to highlight anything new since you previously read the file, and planned to run with no git at all. 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.

Updates on progress: sashmark.com.