How to highlight text in Markdown: what pandoc does

You wrapped a phrase in double equals signs so it would stand out, but pandoc's output still had the signs sitting in the sentence. Or one pandoc command gave you a highlight and the next one stopped with an error.

Here's how to highlight text in Markdown three ways, each run once through pandoc 3.8.3: ==text== with pandoc's mark extension, a raw HTML <mark> tag, and a bracketed span with a mark class. Every result below is pandoc's output from this test.

What CommonMark gives you

The CommonMark spec, at version 0.31.2, has no section on highlighting. Searching the spec file for the word "highlight", with case ignored, matched 0 lines. The spec has 13 lines that hold two equals signs in a row, and in each of them the signs are part of a run of three or more. A search for exactly two equals signs in a row matched 0 lines.

Here's the test file, mark-basic.md:

Jane signs the ==Doe Holdings== plan.

With pandoc -f commonmark -t html mark-basic.md, pandoc gave <p>Jane signs the ==Doe Holdings== plan.</p>. The equals signs stayed in the sentence, and no highlight element came out.

The mark extension in pandoc

Pandoc names this syntax the mark extension. In this test, pandoc's list of default extensions for its markdown reader showed -mark, so the extension starts switched off there. That's why the output of pandoc -f markdown -t html mark-basic.md matched the commonmark run, equals signs and all.

To switch it on, add +mark to the reader name:

pandoc -f markdown+mark -t html mark-basic.md

Pandoc gave <p>Jane signs the <mark>Doe Holdings</mark> plan.</p>. The signs were gone, and the phrase sat inside a <mark> element.

The commonmark reader refused the same flag. Pandoc printed two lines and no HTML for pandoc -f commonmark+mark -t html mark-basic.md:

The extension mark is not supported for commonmark.
Use --list-extensions=commonmark to list supported extensions.

Pandoc then exited with code 23. The same refusal and the same exit code came back for each of the six files run with commonmark+mark in this test. In this test, the setting that turned ==text== into a <mark> element was markdown+mark.

Raw HTML mark tags

The second form skips Markdown syntax and writes the tag by hand. The spec's section on raw HTML (lines 8177 to 8181) says text between < and > that looks like an HTML tag is parsed as a raw HTML tag and rendered in HTML without escaping. It also says tag names aren't limited to current HTML tags.

The test file mark-html.md held this line:

Jane signs the <mark>Doe Holdings</mark> plan.

Under commonmark, markdown and markdown+mark, pandoc gave <p>Jane signs the <mark>Doe Holdings</mark> plan.</p>, with the tag passed through as written. The run with commonmark+mark stopped with exit code 23, as in the previous section.

What happens to raw HTML after pandoc is a separate topic. The raw HTML guide walks through inline tags, HTML blocks and the blank-line rule, so this post won't repeat them.

Bracketed span with a mark class

Pandoc's markdown reader has a bracketed_spans extension. The extension lists pandoc printed here showed it on by default for markdown and off by default for commonmark. The test line below wraps the words in square brackets and adds the class in curly braces right after them.

The test file mark-span.md:

Jane signs the [Doe Holdings]{.mark} plan.

With pandoc -f markdown -t html mark-span.md, pandoc gave <p>Jane signs the <mark>Doe Holdings</mark> plan.</p>. That command did not add +mark, and the output still held a <mark> element. Adding +mark gave the same line.

With pandoc -f commonmark -t html mark-span.md, the brackets and braces stayed as text: <p>Jane signs the [Doe Holdings]{.mark} plan.</p>.

Highlight and bold together

Two extra test files put the mark extension next to bold. For the star rules themselves, the bold and italic post has the details.

The first file wraps the highlight in bold:

Jane signs the **==Doe Holdings==** plan.

With markdown+mark, pandoc gave <strong><mark>Doe Holdings</mark></strong> inside the paragraph. The second file swaps the order:

Jane signs the ==**Doe Holdings**== plan.

Here pandoc gave <mark><strong>Doe Holdings</strong></mark>. Both orders gave a <mark> element and a <strong> element, nested the way the markers were.

Under commonmark and plain markdown, both files came out bold, and the equals signs stayed as text, for example <strong>==Doe Holdings==</strong>.

When the equals signs stay literal

Even with markdown+mark, some test lines kept their equals signs. These cases were run with pandoc -f markdown+mark -t html, one test file per case.

1. Spaces inside the signs. For Jane signs the == Doe Holdings == plan., pandoc gave the line back with the signs and spaces in place, and no <mark> element.
2. A backslash before the signs. For Jane signs the \==Doe Holdings\== plan., pandoc gave Jane signs the ==Doe Holdings== plan. inside a paragraph. At line 481, the spec's backslash escapes section lets any ASCII punctuation mark take a backslash, and its example on the next lines includes the equals sign. The escape characters post covers escapes in general.
3. A code span. A test line held a code span with ==Doe Holdings== inside it, and pandoc gave <code>==Doe Holdings==</code> under all three readers that ran.

A word with no spaces around the signs went the other way. For Doe==Holdings==plan, markdown+mark gave Doe<mark>Holdings</mark>plan, with the highlight landing inside the word. Under commonmark and plain markdown, the same line came back unchanged.

Test your own file

When a highlight doesn't come out as you planned, check the line on its own.

1. Copy the line with the highlight into a scratch file.
2. Run pandoc -f commonmark -t html with your file name, the way pandoc -f commonmark -t html mark-basic.md was run here. If the equals signs come back in the text, you're seeing what this test saw under that reader.
3. Run pandoc -f markdown+mark -t html with your file name and read the output for a <mark> element.
4. To check for them, pipe the output to grep; grep -c counts lines that hold a match. This test printed 1 for pandoc -f markdown+mark -t html mark-basic.md | grep -c '<mark>', and 0 for the same command on mark-spaced.md.
5. If the count is 0, look for spaces inside the signs, a backslash before them, or backticks around them.
6. When the file has to stay CommonMark, write the raw HTML tag instead, run step 2 again, and check that the <mark> element came through.

Where Sashmark fits

Sashmark's v1 plan is set to let you make in-place edits on the rendered page itself, and lines you never touched should stay identical, byte for byte, thanks to a planned clean Round-Trip. Its planned Changes View would mark what differs from your last read of the file, 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.

Keep an eye on sashmark.com for progress.