---
title: "Markdown image link: a linked image in four pandoc tests"
slug: markdown-image-link
excerpt: "A markdown image link on a line by itself, as pandoc wrote it in one test, is quoted under The image alone on its line."
quickAnswer: "The section Four test files with a linked image lists the inputs and the reader settings. HTML for a linked image with no other text on its line is quoted in The image alone on its line. A sentence that holds the linked image is covered under A linked image inside a sentence. Pandoc's output for the labeled file is quoted in Reference style with two definitions. Where pandoc put two title attributes is shown in Two titles, one on each element. Figure counts and extension listings appear in No figure element in these runs. CommonMark line references are gathered in Images as link text in the spec. Commands and numbered steps make up Check a linked image with pandoc."
keyTakeaways:
  - "Under The image alone on its line, pandoc's HTML is quoted for three reader settings."
  - "The section A linked image inside a sentence shows pandoc's HTML when words surround the linked image."
  - "The section Reference style with two definitions quotes pandoc's output for the labeled file."
  - "Where pandoc put the two title attributes is quoted in Two titles, one on each element."
  - "Counts from grep and two extension listings sit under No figure element in these runs."
publishedDate: 2026-10-21
dateModified: 2026-10-21
author: Bobby Huang
cluster: B
role: post
status: published
faq:
  - q: How do I wrap a Markdown image in a link?
    a: "Input lines used here appear in Four test files with a linked image. The steps sit under Check a linked image with pandoc."
  - q: Did pandoc turn my linked image into a figure?
    a: "Under No figure element in these runs, the figure counts and extension listings from this test are quoted."
  - q: Can a linked image use reference definitions?
    a: "HTML that pandoc wrote for the labeled file is quoted under Reference style with two definitions."
  - q: Which tag gets which title?
    a: "The section Two titles, one on each element quotes pandoc's output for an input carrying two titles."
related:
  - markdown-images
  - markdown-image-size
  - markdown-reference-links
---

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:

```sh
cat il-alone.md
```

```text
[![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](markdown-images.md).

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

```text
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:

```text
[![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:

```text
[![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:

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

Output:

```html
<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:

```html
<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:

```html
<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](markdown-reference-links.md), 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:

```html
<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:

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

```text
+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`:

```sh
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](markdown-image-size.md).

## 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](markdown-images.md).

## Check a linked image with pandoc

Each of these commands ran in this test:

```sh
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](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

More at [sashmark.com](https://www.sashmark.com/).