Markdown image link: a linked image in four pandoc tests

A markdown image link puts image syntax where the text of a link would go. Four small files tried that idea in this test, and pandoc gave one shape for them under three reader settings: a p element, an a element inside it, and an img element inside the a. No run here wrote a figure element.

The runs happened once per setting on a single macOS machine. Asked for its version, pandoc there answered 3.8.3. This post reports the elements and attributes pandoc wrote, and it makes no claim about what any viewer does with them.

Four test files with a linked image

Here is each file, printed with cat. The first one:

cat il-alone.md

[![Doe Holdings logo](logo.png)](https://example.com)

Read it from the inside out. The part ![Doe Holdings logo](logo.png) is an image, and that whole image sits inside the square brackets of a link. The link's target, https://example.com, follows in the outer parentheses. For image syntax, paths and alt text, see the Markdown images guide.

The second file sets the same linked image mid-sentence:

See the [![Doe Holdings logo](logo.png)](https://example.com) badge.

The third uses labels for both parts, with two definition lines after a blank line:

[![Doe Holdings logo][logo]][site]

[logo]: logo.png
[site]: https://example.com

The fourth adds a title in double quotes to the image and another to the link:

[![Doe Holdings logo](logo.png "Logo title")](https://example.com "Link title")

Those files are il-alone.md, il-inline.md, il-ref.md and il-title.md. Pandoc converted each file to HTML three times, once per -f value: markdown, markdown-implicit_figures and commonmark. That makes twelve runs, and the log shows rc=0 for all twelve.

The image alone on its line

The command:

pandoc -f markdown -t html il-alone.md

Output:

<p><a href="https://example.com"><img src="logo.png"
alt="Doe Holdings logo" /></a></p>

The outer element is a p. Inside it, the a carries href="https://example.com" from the link's parentheses. Inside the a, the img carries src="logo.png" and alt="Doe Holdings logo", both taken from the image part. The output line ends after src="logo.png", and this post keeps that break where the log put it.

The markdown-implicit_figures run and the commonmark run wrote the same two lines. So for this file, turning the figure extension off and switching to the commonmark reader both left the output as it was.

A linked image inside a sentence

For il-inline.md, where words surround the linked image, the markdown reader gave:

<p>See the <a href="https://example.com"><img src="logo.png"
alt="Doe Holdings logo" /></a> badge.</p>

The words "See the" and "badge." stayed plain text inside the same p, before and after the a. The a and img match the first file's output, attribute for attribute. Both other reader settings printed these two lines unchanged.

Reference style with two definitions

In il-ref.md, the image points at the label logo and the link points at the label site. Two definition lines below give those labels their targets. Under all three settings, pandoc wrote:

<p><a href="https://example.com"><img src="logo.png"
alt="Doe Holdings logo" /></a></p>

This matches what the first file produced. The definition lines left nothing behind in the HTML; their targets moved into href and src. How a definition line is built and how labels match is covered in the reference links walkthrough, so this post leaves those rules there.

Two titles, one on each element

The file il-title.md has a quoted title inside the image's parentheses and a second one inside the link's parentheses. Under all three settings, pandoc wrote:

<p><a href="https://example.com" title="Link title"><img src="logo.png"
title="Logo title" alt="Doe Holdings logo" /></a></p>

The attribute title="Link title" landed on the a. The attribute title="Logo title" landed on the img, ahead of alt. Here, then, the title inside the inner parentheses stayed with the image, and the outer title stayed with the link.

No figure element in these runs

Pandoc lists the extensions each reader turns on. Filtering those lists for the figure extension printed:

pandoc --list-extensions=markdown | grep implicit_figures
pandoc --list-extensions=commonmark | grep implicit_figures

+implicit_figures
-implicit_figures

The plus sign means implicit_figures was on for the markdown reader. The minus sign means it was off for commonmark. So of the three settings, only one had the extension switched on: plain markdown.

Even so, the markdown run on il-alone.md, with the linked image alone on its line and the extension on, wrote no figure element. To count, this test piped output into grep -c:

pandoc -f markdown -t html il-alone.md | grep -c '<figure'
pandoc -f markdown -t html il-alone.md | grep -c '<img'

The first command printed 0 and the second printed 1. The img count works as a control: it proves the search reached the output and found a tag that was there. The same two counts, 0 and 1, came back for all four files under all three settings.

What the runs show is narrow. The paragraph held a link, the image sat inside that link, and no figure appeared. For when pandoc does wrap an image in a figure, and how to switch that off, see the image size and figures walkthrough.

Images as link text in the spec

For spec lines, this post read the CommonMark text tagged 0.31.2. Its section on links covers this case. Line 7215 states that link text may contain inline content. Example 517, on lines 7223 to 7227, uses an image as the whole link text, and the expected result there is a p with an a holding an img, the same nesting pandoc wrote here.

The reference form appears too. Lines 7361 to 7365 give an example where an inline image is the text of a link that uses a label, with the same nesting in the expected result.

For image syntax beyond its use as link text, see the Markdown images walkthrough.

Check a linked image with pandoc

Each of these commands ran in this test:

cat il-alone.md
pandoc -f markdown -t html il-alone.md
pandoc -f markdown-implicit_figures -t html il-alone.md
pandoc -f commonmark -t html il-alone.md
pandoc -f markdown -t html il-alone.md | grep -c '<figure'
pandoc -f markdown -t html il-alone.md | grep -c '<img'
pandoc --list-extensions=markdown | grep implicit_figures
pandoc --list-extensions=commonmark | grep implicit_figures

To test a linked image of yours, replace il-alone.md with your own Markdown file.

1. Print the source line. With cat, confirm the image part sits inside the square brackets of the link.
2. Convert it with the markdown reader. Here the output held an a with an img inside it, both inside a p.
3. Convert it again with markdown-implicit_figures and with commonmark. Here, all three outputs matched for the same file.
4. Count figure tags with grep -c, and count img tags as a control. This test printed 0 and 1.
5. If you used titles, find which tag holds which title attribute. The inner title stayed on the img and the outer one on the a in this test.
6. List the reader's extensions and look for implicit_figures, so you know whether the figure extension was on for your run.

Where Sashmark fits

Picture Sashmark's v1 arriving as planned. You might then alter a line in place mid-read, and clean Round-Trip, a part on the planned list, would save the file again with each skipped line byte-for-byte unchanged. Also slated for that version: a Changes View, expected to show what moved after your latest visit to the file, with git kept out of it.

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.

More at sashmark.com.