The Image Size You Set in One App Becomes Alt Text in the Next

Markdown has no place for an image's size, so each app invents one — and outside that app, the size turns into something else. Write it the way Obsidian's help page shows, and every renderer we tested put the number in the alt text. That is the text a screen reader can read aloud instead of the picture.

Here is the line Obsidian's help uses to show how to size a remote image. The sentence above it reads: "You can also embed an externally hosted image by using a Markdown link. You can control the width and height using the same syntax as a wikilink."¹

![250](https://publish-01.obsidian.md/access/f786db9fac45774fa4f0d8112e232d67/Attachments/Engelbart.jpg)

Inside Obsidian, per that page, the 250 is a width. In all nine configurations we ran on 2026-10-27, it became the alt text — alt="250", with no width.²

The question behind this is one of the busiest on Stack Overflow. "Changing image size in Markdown," asked on 2013-02-03, had 2,053,284 views, a score of 1,910 and 41 answers when we read it on 2026-10-27.³ Its answers name syntaxes. They rarely say what each one becomes in the next app.

So we measured four ways of writing "make this picture 300 wide" in nine default configurations, with pinned versions. What follows is the table, the reason behind each row, and a rule for choosing by destination.

Why does my Markdown image show "|300" in other apps?

Because the |300 sits inside the brackets, and in standard Markdown the brackets hold the image description. Obsidian reads a trailing number there as a size. Every renderer we tested read the whole bracket — Diagram|300 — as the alt text, and one of them also printed it under the picture as a caption.

The common form in notes is a short description followed by the size:

![Diagram|300](diagram.png)

Obsidian's help documents the size rule for its own embeds — "You can change the image dimensions by adding |640x480 to the link destination, where 640 is the width and 480 is the height" — and says the same syntax works for Markdown links.¹ That is a reasonable convenience inside one app.

Outside it, the result was identical in nine of nine configurations:²

<img src="diagram.png" alt="Diagram|300" />

pandoc's own Markdown went one step further. Its figure rule says an image alone in a paragraph "will be rendered as a figure with a caption. The image's description will be used as the caption."⁴ So the size became visible text under the image:

<figure>
<img src="diagram.png" alt="Diagram|300" />
<figcaption aria-hidden="true">Diagram|300</figcaption>
</figure>

Sighted readers see "Diagram|300" under the picture. The caption carries aria-hidden="true", which marks it to be skipped by assistive technology — the alt attribute already holds the same text.

GitHub rendered the same alt and wrapped the image in a link to the file.

The leak is known inside the Obsidian ecosystem. One community plugin, Image Title, lists this feature: "Automatically strips Obsidian size parameters (|600, |200x300) from captions".⁵ A plugin exists to take the number back out.

Why doesn't Markdown have a way to set image size?

The CommonMark specification gives an image three parts — a description, a destination and an optional title — and no fourth part for size. Anything an app wants to add has to be squeezed into one of those three slots, or written outside them, where other parsers see stray text.

The spec's image section ends on a rendering recommendation that matters here: "Though this spec is concerned with parsing, not rendering, it is recommended that in rendering to HTML, only the plain string content of the image description be used."⁶ In practice, the description becomes alt. A size typed into the description travels with it.

The link rules close the other door. "An inline link consists of a link text followed immediately by a left parenthesis (, an optional link destination, an optional link title, and a right parenthesis )."⁷ Images use the same parentheses. After the destination, the parser expects a title or the closing parenthesis — not =300x.

So every sizing syntax picks a slot:

![ description ]( destination  "title" ){ after }
    ^ Obsidian      ^ =300x suffix       ^ pandoc {width=300}

Only the description slot is guaranteed to survive — which is exactly why a size placed there leaks.

A fifth form, Obsidian's wikilink embed ![[diagram.png|300]], printed as literal text in all nine configurations. That one is about where the file lives, not its size. Our piece on why Markdown is portable until you add an image covers it, with paths and attachment folders.

This piece is the next step of that advice. Plain ![alt](path) travels — as long as the alt holds a description and nothing else.

Four image-size syntaxes, measured in nine renderers

Only the HTML <img> tag carried a width of 300 through most renderers — eight of nine. pandoc's {width=300} worked in two, both pandoc readers. The Obsidian form and the =300x suffix carried the size in none. Each row below is one default configuration, run on 2026-10-27 with the versions named.

The test cases, saved as one file each:

![Diagram|300](diagram.png)
![Diagram](diagram.png){width=300}
![Diagram](diagram.png =300x)
<img src="diagram.png" alt="Diagram" width="300">

Obsidian's own ![250](…) example behaved exactly like the first column: alt="250" in nine of nine.

Plugins change the picture, but only where someone switched them on. markdown-it with markdown-it-attrs 5.0.1 sized {width=300}; with markdown-it-imsize 2.0.1 it sized =300x; Python-Markdown's attr_list extension sized {width=300}.

Each JavaScript row can be reproduced with a few lines:²

// npm i [email protected] [email protected]
import MarkdownIt from 'markdown-it';
import * as commonmark from 'commonmark';

const note = '![Diagram|300](diagram.png)\n';
console.log(new MarkdownIt('commonmark').render(note));
console.log(new MarkdownIt().render(note));
console.log(new commonmark.HtmlRenderer().render(new commonmark.Parser().parse(note)));

All three print an image whose alt is Diagram|300.

What pandoc's {width=300} turns into outside pandoc

Only two readers honoured {width=300} — pandoc's own markdown and commonmark_x. Everywhere else it was text after an image: CommonMark renderers, GitHub, Python-Markdown and pandoc's stricter readers emitted the picture with no width and printed {width=300} beside it. Some plugins accept it too, where switched on.

pandoc's manual introduces it plainly: "Attributes can be set on links and images:" It adds that "The width and height attributes on images are treated specially. When used without a unit, the unit is assumed to be pixels."⁸ Inside pandoc, it is the cleanest syntax of the four — the description stays a description.

Elsewhere, the stray braces came out like this — commonmark.js shown:

<img src="diagram.png" alt="Diagram" />{width=300}

The same image inside a sentence — See ![Diagram](diagram.png){width=300} here. — kept its width in pandoc's markdown reader but did not become a figure, since the figure rule needs the image alone in its paragraph.⁴

Python-Markdown's attribute lists accept a colon form too. Its documentation says: "A colon after the opening brace is optional, but is supported to maintain consistency with other implementations."⁹

![Diagram](diagram.png){: width="300"}

That colon is not universal. markdown-it-attrs handled {: width="300"} by adding the width and a junk attribute named :.²

pandoc also offers the one automatic way out. Converting a note with pandoc -f markdown -t gfm rewrote the sized image as HTML:

<figure>
<img src="diagram.png" width="300" alt="Diagram" />
<figcaption aria-hidden="true">Diagram</figcaption>
</figure>

The size survives export — as HTML. The Obsidian form exported the same way kept Diagram|300 in both the alt and the caption.²

Why the =300x suffix stops being an image

In standard Markdown, a space followed by =300x inside the parentheses is neither part of the address nor a valid title, so the parser gives up on the image. Seven of nine configurations printed the whole line as text. The other two kept the image but folded =300x into a broken file path.

The suffix is not obscure. The second-ranked answer on the Stack Overflow question, with a score of 962, teaches it: "With certain Markdown implementations (including Mou and Marked 2 (only macOS)) you can append =WIDTHxHEIGHT after the URL of the graphic file to resize the image."¹⁰

Microsoft documents the same family for Azure DevOps wikis. Its guide tells writers to "Include a space before the equal = sign." For width alone: "You still need to include the letter x."¹¹ The example:

![Image alt text](./image.png =500x250)

A markdown-it plugin implements it too — the markdown-it-imsize README shows ![test](image.png =100x200) and says it "is interpreted as" an <img> with width="100" and height="200".¹² Its repository was last updated in 2018.

Without such a plugin, the outcomes were blunt:

<p>![Diagram](diagram.png =300x)</p>

That is markdown-it's output. commonmark.js, GitHub and three of pandoc's readers also printed the line as text. pandoc's own markdown reader requested diagram.png%20=300x; Python-Markdown requested diagram.png =300x.²

The suffix is a dialect. It works in the tools that speak it.

The HTML img tag: the size survives, the alt is on you

Writing the image as an HTML tag carried the width in eight of nine configurations — the most portable result in the test. The exception is any renderer that switches raw HTML off; there, the tag printed on the page as text. The tag also has a second cost: nothing fills in alt for you.

The Stack Overflow question's accepted answer, scored 1,972, begins "You could just use some HTML in your Markdown" and gives a tag of the form <img src="drawing.jpg" alt="drawing" width="200"/>.¹³ It is good advice with one condition attached.

The condition is raw HTML. markdown-it's default preset ships with these two lines:¹⁴

// Enable HTML tags in source
html: false,

With that default, the tag is escaped and shown to the reader:

<p>&lt;img src=&quot;diagram.png&quot; alt=&quot;Diagram&quot; width=&quot;300&quot;&gt;</p>

That same switch decides what happens to HTML comments, which our piece on hiding a comment in a Markdown note measured across ten tools.

The second cost is quieter. Tools that write the tag for you may leave alt out. The Image to HTML plugin for Obsidian argues that "HTML image tags offer better compatibility across different platforms compared to Markdown or Obsidian's wikilink format." Its README also says: "By default, the plugin generates HTML tags without the alt attribute to keep the code concise."¹⁵

So the HTML route trades one risk for another — the size survives, and the description is yours to write.

GitHub is a common destination for this tag. Its documentation's Images section, read on 2026-10-27, describes no size syntax at all.¹⁶

What a number in the alt text costs

Alt text is the part of an image that reaches people and tools that cannot see it. A size number in that slot replaces the description — "250" in place of a portrait, "Diagram|300" in place of a diagram's point. Standards bodies agree the slot should hold a short replacement for the image, not a dimension.

The HTML standard sets the bar: "Except where otherwise specified, the alt attribute must be specified and its value must not be empty; the value must be an appropriate replacement for the image."¹⁷ It offers a test: "One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present."

Read "Diagram|300" to someone over the phone and the test answers itself.

W3C's accessibility tutorial puts it in one line: "The alt text should be the most concise description possible of the image's purpose."¹⁸ It also names who receives it — "People using screen readers: The text alternative can be read aloud or rendered as Braille".¹⁹ GitHub's docs say the same in fewer words: "Alt text is a short text equivalent of the information in the image."¹⁶

Alt text on the web is already weak. WebAIM's 2026 scan of a million home pages found that "16.2% of all home page images (10.8 per page on average) had missing alternative text (not counting alt="" )." It also found that "10.8% of images with alternative text had questionable or repetitive alternative text—such as alt="image", "graphic", "blank", a file name, etc."²⁰ A size number is one more way to land there — our inference, not WebAIM's category.

The second reader is a machine. A text-only AI assistant searching your notes sees the alt and nothing else — see alt text your images so your AI can see them for why that slot matters.

How to choose an image size syntax by destination

Pick the syntax by where the note will be read, not by where it is written. A note that stays in one app can use that app's syntax. A note that must read correctly anywhere should carry no size. A note published as HTML can use an <img> tag with a written alt. A pandoc document can use {width=…}.

The four cases:

1. The note stays in one app. Its syntax is fine. If that syntax puts the number in the description slot, the number becomes alt text the moment the file opens elsewhere.
2. The note must read correctly anywhere. Use plain ![a real description](file.png) with no size, and let the viewer scale it.
3. The note is published where raw HTML is allowed — a GitHub README, or a site whose generator passes HTML through. Use <img src="file.png" alt="a real description" width="300">, and write the alt yourself.
4. The note goes through pandoc. {width=300} is native, and exporting to gfm or commonmark writes the HTML for you.

The rule that holds in all four: never put a number where the description goes.

A quick audit finds the risky lines in a folder of notes. This search flags images whose description ends in a pipe and digits, and images whose bracket holds only digits:

grep -rnE '!\[[^]]*\|[0-9]+(x[0-9]+)?\]\(|!\[[0-9]+(x[0-9]+)?\]\(' notes/

Each hit is a description to rewrite — the size can move to an <img> tag, a pandoc attribute, or nowhere at all.

A before-and-after for the second case:

<!-- before: the size is the alt text everywhere but one app -->
![Diagram|300](diagram.png)

<!-- after: portable, and the alt says what the diagram shows -->
![Flowchart: draft, review, publish, with a loop from review back to draft](diagram.png)

What this test does not show

Nine default configurations are a sample, not the web. Obsidian itself was not run — its behaviour here is what its help page documents. No screen reader was tested, and renderers change between releases. The table answers "what did this version do with this line," nothing broader.

Obsidian was documented, not measured. That the |300 form sizes the image inside Obsidian comes from its help page.¹ We did not test what alt text Obsidian writes into its own view.

No screen reader was run. The claim stops at what the HTML contains. How a given screen reader announces "Diagram|300" or "250" was not tested.

Versions drift. pandoc 3.13 was released the day before the run. GitHub's renderer has no public version number, so its row is a snapshot of one day.

Some hosts were not measured. Docusaurus, Bitbucket wikis and many site generators have their own rules and raw-HTML settings; each needs its own check.

Plugins were tested only where named. A renderer you use may ship one of them switched on.

Frequently Asked Questions

How do I change image size in Markdown?

Standard Markdown has no image-size syntax. Where raw HTML is allowed, <img src="file.png" alt="description" width="300"> carried the width in eight of nine renderers we tested on 2026-10-27. pandoc users can write ![description](file.png){width=300}. App-specific forms such as |300 and =300x work only in the apps that define them.²⁶

Why does my image show "|300" in the alt text?

The |300 was typed inside the image's square brackets, which standard Markdown treats as the image description. Obsidian reads a trailing number there as a size. Every renderer we tested — nine of nine — used Diagram|300 as the alt text, and pandoc also printed it as a visible caption.¹²

Does Obsidian's image size syntax work in other apps?

No, not in any of the nine configurations we tested. Obsidian's help page says a Markdown link can take a size "using the same syntax as a wikilink," with an example whose bracket holds only 250. Elsewhere, that image's alt text was "250" and no width was set. The wikilink form printed as text.¹²

How do I resize an image in a GitHub README or wiki?

Use an HTML tag such as <img src="diagram.png" alt="A short description" width="300">. GitHub's renderer kept that width in our test. Its documentation's Images section describes no size syntax, and {width=300} and =300x printed as text there. The related Stack Overflow question had 408,091 views.¹⁶²¹

Why does  not work?

In standard Markdown, the space and =300x after the address are neither part of the address nor a valid link title, so the line is not parsed as an image. Seven of nine configurations printed it as text. The suffix works only where a tool defines it, such as Azure DevOps wikis or the markdown-it-imsize plugin.⁷¹¹¹²

What should image alt text say instead of a size?

A short replacement for the image — what it shows or what it is for. The HTML standard asks for "an appropriate replacement for the image," and W3C's tutorial asks for "the most concise description possible of the image's purpose." A number like "250" or "Diagram|300" meets neither.¹⁷¹⁸

A size is an instruction to one viewer. A description is for every reader who comes after.

Keep them in separate slots.

MNMNOTE keeps your notes as open Markdown on your own device — plain files any other app can open and read. mnmnote.com

References