Markdown image size: width attributes in pandoc tests

A screenshot lands in your Markdown file and comes out wider than the text around it. You want to give that one image a width.

Here, markdown image size markup goes into one pandoc run on macOS. Pandoc reported itself as 3.8.3. The tests cover a width in curly braces, pixel units, a typed img tag, and LaTeX output. Test files are named next to their results so you can rerun them. Results end at what pandoc printed; no viewer's drawing of that output was tested.

Size words in the CommonMark spec

Image basics such as paths and alt text live in the image basics guide. Here the question is whether CommonMark, in its 0.31.2 text, defines size syntax at all.

Grep found no size markup in the spec file. The case-blind grep -ci 'height' returned 0. A whole-word grep -ciw 'size' returned 0, and grep -c '{width' returned 0 too. The word width turned up on 4 lines (3819, 4106, 4254 and 4731), and all four describe the width of a list marker. For a control, grep -ci 'image' on the same file returned 22.

The routes tested below are a pandoc extension and typed HTML. Running pandoc --list-extensions=markdown listed +link_attributes and +raw_html. For pandoc --list-extensions=commonmark, the lines were -attributes and +raw_html.

Width in curly braces after the image

The test file img-attr.md put a width in braces right after the closing parenthesis:

![Logo](logo.png){width=50%}

Four reader settings gave these results:

• pandoc -f markdown -t html img-attr.md put style="width:50.0%" on the img, inside a figure. The full output is quoted under When an image becomes a figure.
• pandoc -f commonmark+attributes -t html img-attr.md returned <p><img src="logo.png" style="width:50.0%" alt="Logo" /></p>.
• pandoc -f commonmark -t html img-attr.md returned <p><img src="logo.png" alt="Logo" />{width=50%}</p>. The braces printed as text right after the img.
• With pandoc -f markdown-link_attributes -t html img-attr.md, the output matched the plain commonmark line, braces included.

The percent value went into a style attribute, written as 50.0%. With the extension off, the width was left as plain text beside the tag.

Pixel units and two dimensions

The second test file, img-px.md, set a width and a height with a unit:

![Logo](logo.png){width=200px height=100px}

Each reader setting returned the following:

• pandoc -f markdown -t html img-px.md gave a figure holding <img src="logo.png" width="200" height="100" alt="Logo" />.
• pandoc -f commonmark+attributes -t html img-px.md returned <p><img src="logo.png" width="200" height="100" alt="Logo" /></p>.
• pandoc -f commonmark -t html img-px.md returned <p><img src="logo.png" alt="Logo" />{width=200px height=100px}</p>.

Here pandoc dropped the px unit and wrote plain width and height attributes. Compare that with the percent test, where the value went into style. Both values in one set of braces came through.

When an image becomes a figure

The markdown reader wrapped img-attr.md in more than a paragraph. Its full output:

<figure>
<img src="logo.png" style="width:50.0%" alt="Logo" />
<figcaption aria-hidden="true">Logo</figcaption>
</figure>

The figcaption held the alt text, Logo. In the added test's extension listing, markdown showed +implicit_figures and commonmark showed -implicit_figures. Turning it off kept the width and dropped the figure: pandoc -f markdown-implicit_figures -t html img-attr.md returned <p><img src="logo.png" style="width:50.0%" alt="Logo" /></p>.

An image with words on the same line stayed a plain img. The test file img-inline.md:

Inline ![Logo](logo.png){width=40} here.

The markdown reader and the commonmark+attributes setting both returned <p>Inline <img src="logo.png" width="40" alt="Logo" /> here.</p> for this file. A bare number with no unit became a width attribute. With plain commonmark, the output was <p>Inline <img src="logo.png" alt="Logo" />{width=40} here.</p>.

A typed img tag that sets width

For typed HTML beyond this one tag, read the raw HTML guide. The file img-raw.md holds a single tag:

<img src="logo.png" alt="Logo" width="200">

Results:

• pandoc -f markdown -t html img-raw.md returned <p><img src="logo.png" alt="Logo" width="200"></p>.
• pandoc -f commonmark -t html img-raw.md returned <img src="logo.png" alt="Logo" width="200"> with no paragraph around it.
• pandoc -f commonmark+attributes -t html img-raw.md gave that same bare line.

Start condition 7 in the spec (lines 2247 to 2251) fits this file: its one line holds a complete open tag whose name, img, is not among the four names that condition leaves out, and nothing follows the tag. In both readers' output, the attributes kept their typed order.

Image width in LaTeX output

Pandoc can write LaTeX too, and the width carried over. Here is the LaTeX that pandoc -f markdown -t latex img-attr.md printed:

\begin{figure}
\centering
\includegraphics[width=0.5\linewidth,height=\textheight,keepaspectratio,alt={Logo}]{logo.png}
\caption{Logo}
\end{figure}

The 50% width became 0.5\linewidth. Pointing the same LaTeX command at img-px.md gave \includegraphics[width=2.08333in,height=1.04167in,alt={Logo}]{logo.png}, inside the same figure lines. The pixel values came out as inch values.

Check an image width with pandoc

When a width you typed seems to go missing, test that one image line by itself.

1. Copy the image line into an empty file of its own, then print it with cat img-attr.md to confirm the braces sit right after the closing parenthesis.
2. Next, convert it: pandoc -f commonmark -t html img-attr.md. If {width=50%} shows in the output, this reader built no attribute in this test.
3. Count the result. pandoc -f commonmark -t html img-attr.md | grep -c 'style=' printed 0. The same count with -f commonmark+attributes printed 1.
4. Check for a figure. pandoc -f markdown -t html img-attr.md | grep -c '<figure>' printed 1, and the commonmark run of that count printed 0.
5. To keep the width and skip the figure in the markdown reader, append -implicit_figures to the reader: pandoc -f markdown-implicit_figures -t html img-attr.md.
6. For LaTeX, look for width= inside the \includegraphics options that pandoc -f markdown -t latex img-attr.md prints.

Where Sashmark fits

Under Sashmark's v1 plan, you would change text directly in the rendered page. That plan also carries a clean Round-Trip, so any line left unedited would come back out as the exact same bytes. Next on the plan is a Changes View for flagging what is new or different since your last pass over the file; it would not need git. 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.

Project home page: sashmark.com.