Chris Bergeron | Tech Blog

Markdown is a convenient HTML-focused shorthand syntax for formatting content such as documentation and blog articles, but it lacks basic features for image formatting, such as alignment and sizing.
This post presents a variety of ways to format images with Markdown, from brute force to proprietary syntax extensions, unwise hacks, and everything in between.

Here’s how you insert an image in Markdown:

![alt text](/src/of/image.jpg "title")

That is, Markdown allows you to specify an <img> tag with src, alt, and title attributes in HTML.
Standard Markdown doesn’t offer anything beyond this, but it’s very common for websites to need width, height, and CSS class attributes as well.

The rest of this post is dedicated to various solutions to these shortcomings.
To motivate this discussion, I’ll use the example of a large image that should be displayed at a smaller size.

For example,

![Kitten](/media/2018/08/kitten.jpg "A cute kitten")

I won’t show you how to add alignment, floating, or padding—but my sizing example will suffice, because once you know how to change an image’s size, you’ll know how to do other things too.
I’ll show you the best solutions first, and the undesirable ones last.

Use Standard HTML

Markdown was originally designed for HTML authoring, and permits raw HTML anywhere, anytime.
As such, the most straightforward solution is simply to use HTML with the desired attributes:

<img src="/media/2018/08/kitten.jpg" alt="Kitten"
	title="A cute kitten" width="150" height="100" />

This works, and gives you unrestrained control over the resulting HTML.
But Markdown is appealing for its simplicity, unlike HTML that’s cluttered with messy markup.
Thus, many people dislike this solution because it defeats the purpose of Markdown.

Use CSS And Special URL Parameters

In general, the best way to style images is with CSS.
Modern CSS syntax can select elements based on the values of their attributes, so one way to apply CSS rules is to encode extra information into Markdown’s standard src attribute.
In this section I’ll discuss these possibilities.
Later I’ll show you some undesirable CSS-related techniques too.

There are two places in a URL that you can overload to carry information that CSS can use: the URL fragment, and URL query parameters.

The URL fragment is the part that comes after the # character.
When it’s used in a website’s URL, it can scroll the page to bring a desired part of the content into view, but you can add it to images, too.
When you do that, it essentially does nothing as far as the browser is concerned, and a typical user will never see it in the browser’s address bar either.
But it’s useful for our styling needs.
Here we’ll add a thumbnail fragment to the image’s source URL:

![Kitten](/media/2018/08/kitten.jpg#thumbnail)

This information is kept entirely client-side, and browsers don’t transmit this part of the URL to the server when they request content.
However, CSS and JavaScript can read the fragment and use it.
Here’s how to write a CSS selector that will match images with this “thumbnail” information in the URL:

img[src*="#thumbnail"] {
  float: right;
}

The *= selector syntax matches if #thumbnail appears anywhere in the src attribute.
You could also anchor the matching to the end of the URL with $="#thumbnail".

This permits encoding only a single value into the URL, but you can modify this technique to add several.
CSS also has a ~= selector, which matches if the specified value appears exactly in the attribute’s value, as a space-delimited “word,” so to speak.
This lets you simulate combining multiple “classes” in the URL fragment:

![Kitten](/media/2018/08/kitten.jpg# thumbnail bordered)

Now you can target these pseudo “class” names from CSS:

img[src~="thumbnail"] {
   width:150px;
   height:100px;
}
img[src~="bordered"] {
   border: 1px solid black;
}