--- title: "How to highlight text in Markdown: what pandoc does" slug: markdown-highlight-text excerpt: "How to highlight text in markdown: the section The mark extension in pandoc shows the reader flags pandoc accepted and refused in this test." quickAnswer: "The section What CommonMark gives you has a spec search for highlight syntax and one commonmark run. Under The mark extension in pandoc, you'll find the reader setting that worked for ==text== in this test and the one pandoc refused. The section Raw HTML mark tags runs a typed mark tag through four reader settings. Pandoc output for the [text]{.mark} form is in the section Bracketed span with a mark class. Numbered steps for running these checks on a file are in the section Test your own file." keyTakeaways: - "Under What CommonMark gives you, a spec search for highlight syntax sits next to one commonmark test." - "The section The mark extension in pandoc lists which reader flags pandoc accepted and which it refused in this test." - "For a tag typed by hand, the section Raw HTML mark tags shows pandoc output under four reader settings." - "Combining styles is covered in the section Highlight and bold together, with two tested nesting orders." - "Steps for checking a file are numbered in the section Test your own file." publishedDate: 2026-10-20 dateModified: 2026-10-20 author: Bobby Huang cluster: B role: post status: published faq: - q: Is there a highlight syntax in CommonMark? a: "Spec search results and a commonmark test are in the section What CommonMark gives you." - q: Why did pandoc print an error about the mark extension? a: "Error text and the exit code from this test appear in the section The mark extension in pandoc." - q: Why do my equals signs show up in the output? a: "Test cases where the signs stayed as text are in the section When the equals signs stay literal." related: - raw-html-in-markdown - markdown-bold-italic - markdown-escape-characters --- 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 `` 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`: ```markdown Jane signs the ==Doe Holdings== plan. ``` With `pandoc -f commonmark -t html mark-basic.md`, pandoc gave `

Jane signs the ==Doe Holdings== plan.

`. 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: ```sh pandoc -f markdown+mark -t html mark-basic.md ``` Pandoc gave `

Jane signs the Doe Holdings plan.

`. The signs were gone, and the phrase sat inside a `` 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`: ```text 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 `` 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: ```html Jane signs the Doe Holdings plan. ``` Under `commonmark`, `markdown` and `markdown+mark`, pandoc gave `

Jane signs the Doe Holdings plan.

`, 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](raw-html-in-markdown.md) 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`: ```markdown Jane signs the [Doe Holdings]{.mark} plan. ``` With `pandoc -f markdown -t html mark-span.md`, pandoc gave `

Jane signs the Doe Holdings plan.

`. That command did not add `+mark`, and the output still held a `` element. Adding `+mark` gave the same line. With `pandoc -f commonmark -t html mark-span.md`, the brackets and braces stayed as text: `

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

`. ## 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](markdown-bold-italic.md) has the details. The first file wraps the highlight in bold: ```markdown Jane signs the **==Doe Holdings==** plan. ``` With `markdown+mark`, pandoc gave `Doe Holdings` inside the paragraph. The second file swaps the order: ```markdown Jane signs the ==**Doe Holdings**== plan. ``` Here pandoc gave `Doe Holdings`. Both orders gave a `` element and a `` 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 `==Doe Holdings==`. ## 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 `` 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](markdown-escape-characters.md) covers escapes in general. 3. **A code span.** A test line held a code span with `==Doe Holdings==` inside it, and pandoc gave `==Doe Holdings==` 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 `DoeHoldingsplan`, 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 `` 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 ''`, 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 `` 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](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands. Keep an eye on [sashmark.com](https://www.sashmark.com/) for progress.