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]( )
That is, Markdown allows you to specify an
<img> tag with
title attributes in HTML.
Standard Markdown doesn’t offer anything beyond this, but it’s very common for websites to need
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.
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.
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"
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.
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
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
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:
This information is kept entirely client-side, and browsers don’t transmit this part of the URL to the server when they request content.
Here’s how to write a CSS selector that will match images with this “thumbnail” information in the URL:
*= selector syntax matches if
#thumbnail appears anywhere in the
You could also anchor the matching to the end of the URL with
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:
Now you can target these pseudo “class” names from CSS: