Markdown text color: pandoc spans, HTML tags and tests

You wrapped a name in a span with a red style, ran pandoc, and the style came back attached to the HTML. Whether anyone sees red is a separate question, and pandoc doesn't answer it.

To see how markdown text color comes through, these tests ran pandoc 3.8.3 once, on a Mac. They try hand-typed HTML tags, bracketed spans with a style or a class, and what changed when pandoc's raw HTML extension was switched off. Each output quoted here comes from those runs.

Color in plain CommonMark

Color gets no syntax anywhere in CommonMark's 0.31.2 rules. Run over the spec, a case-insensitive grep -ci 'color' matched 6 lines. All six sit inside CSS in two HTML block examples: h1 {color:red;} and p {color:blue;} in Example 172 (lines 2605 to 2615), and <style>p{color:red;}</style> in Example 176 (lines 2664 and 2667). A grep for the British spelling, colour, matched 0 lines. As a control, the same grep for emphasis matched 104.

Two routes got tested here: HTML you type yourself, and pandoc's bracketed_spans extension. When asked, pandoc reported +raw_html and -bracketed_spans as the commonmark reader's extension settings.

Typed span and font tags

The first route puts the color inside a tag you type. This section sticks to two color tests.

The test file color-html.md held one line:

<span style="color: red">Jane Doe</span>

For this one, pandoc -f commonmark -t html color-html.md gave back <p><span style="color: red">Jane Doe</span></p>. Swap in -f markdown and the HTML stays identical.

The older font tag got the same treatment. The file color-font.md:

<font color="red">Jane Doe</font>

Both readers gave <p><font color="red">Jane Doe</font></p>. Both the tag and its color attribute came through exactly as typed.

Hand-typed HTML has its own rules about blank lines and block tags. For those, read the guide to HTML tags inside a Markdown file.

A span with a style attribute

With bracketed_spans, square brackets hold the words and a pair of curly braces placed straight after holds the attributes. This test's extension listing had it switched on for markdown and switched off for commonmark.

The test file color-span.md:

[Jane Doe]{style="color: red"}

The file went through three reader settings:

• pandoc -f commonmark -t html color-span.md printed <p>[Jane Doe]{style="color: red"}</p>. Brackets and braces came out unchanged.
• pandoc -f commonmark+bracketed_spans -t html color-span.md printed <p><span style="color: red">Jane Doe</span></p>.
• pandoc -f markdown -t html color-span.md printed that span too, with no flag added.

A second file, color-x-inline.md, put the span inside a sentence:

Jane Doe signed for [Doe Holdings]{style="color: red"} today.

With commonmark+bracketed_spans, and again with markdown, pandoc wrapped only the company name in <span style="color: red"> and left the rest of the sentence plain, all in one paragraph. Plain commonmark printed the sentence with its brackets and braces intact.

The same bracket form with an underline class gets its own tests in the post on underlining text.

A class name instead of a style

A span can also hold a class where the style would go. The test file color-class.md:

[Jane Doe]{.red}

Here's what each reader setting printed:

• markdown: <p><span class="red">Jane Doe</span></p>.
• commonmark+bracketed_spans: that same class span.
• Plain commonmark: <p>[Jane Doe]{.red}</p>, braces and all.

One more file, color-x-both.md, gave the span a class and a style at once: [Jane Doe]{.red style="color: red"}. Both of the extension-on settings gave back <p><span class="red" style="color: red">Jane Doe</span></p>.

In each of these runs, pandoc's output stops at an attribute. A style attribute shows color only where the viewer of that HTML keeps the inline style. A class shows color only where a style rule for that class exists, and pandoc wrote no such rule here. Whichever route you pick, do not carry meaning by color alone.

Cases where the markup came back as text

A handful of lines kept their markup visible.

• Plain commonmark on a span. The bracket and brace files above, color-span.md, color-class.md and color-x-inline.md, kept their brackets and braces as plain text inside a paragraph.
• A span inside backticks. The file color-x-code.md wrapped the class span in backticks. Pandoc gave <p><code>[Jane Doe]{.red}</code></p> from both commonmark and markdown.
• The font tag with raw HTML off. In this test, pandoc listed +raw_html and +native_spans for markdown. From pandoc -f markdown-raw_html -t html color-font.md, the angle brackets came back as < and >, so the tag became visible text and no font element was output. Pandoc also swapped the straight quote marks around red for curly ones.
• The span tag with raw HTML off. That same markdown-raw_html setting still printed <p><span style="color: red">Jane Doe</span></p> for color-html.md. With -native_spans added as well, pandoc -f markdown-raw_html-native_spans -t html color-html.md escaped the span tag the way the font tag was escaped.

The backtick test file, color-x-code.md, in full:

`[Jane Doe]{.red}`

Check a line for color output

When a color you expected is missing from the HTML, test that line by itself.

1. Paste the line, alone, into a fresh file.
2. Feed it to plain pandoc -f commonmark -t html. Brackets and braces in the result match what plain commonmark printed in this test.
3. Try -f markdown next. To keep the commonmark reader, add the extension instead: -f commonmark+bracketed_spans.
4. Count matches with grep. For the styled span, pandoc -f markdown -t html color-span.md | grep -c 'color: red' printed 1. Next, pandoc -f commonmark -t html color-span.md | grep -c '<span' printed 0, and swapping in commonmark+bracketed_spans printed 1.
5. A zero count points you to Cases where the markup came back as text.
6. For a class, find class=" in the output, then confirm a style rule for that class exists wherever the HTML gets shown.

Where Sashmark fits

Sashmark's v1 plan lets you change words on the rendered page as you read. Untouched lines would keep their old bytes exactly, since the Round-Trip is planned to stay clean. On top of that, v1 is planned to include a Changes View whose job would be flagging what differs since your last reading, 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.

News on the build: sashmark.com.