Published in January 2024

I really like Markdown as writing format. However, image positioning in Markdown is very basic, which isn’t always ideal. Well, it’s almost never ideal to practically have no control over sizing or alignment of an inline-image in a text.

As a format, Markdown has been around since 2004 and got popular maybe around 2009 or so. By now in 2023, it seems that everything is written in Markdown. Maybe not quite everything, but it kind of is the de facto standard used for simple text formatting online - be it in writing applications, open-source software documentation, project management tools, blogs or even some messengers and social media platforms.

That doesn’t mean that Markdown is perfect. Quickly after starting to play around with Astro, I’ve noticed that even after all these years, positioning and aligning images is still a pain in Markdown. Without it being included in the standard, there are many hacks that add some syntax to align images. The tricky thing is that every Markdown parser and extension tends to support different ways of achieving the same thing.

Now, I’m very happy that Astro supports Markdown out of the box. Unfortunately, I couldn’t find a plugin that would support easy formatting of images.

I came across some potential candidates, like remark-attr, but when I checked it was marked as “broken”. Then I thought remark-directive could be a more generic and powerful, but also perhaps a bit more verbose alternative.

But why is a plugin needed for something so basic?! So I looked for other solutions.

I got some ideas from a Stack Overflow question about “Markdown and image alignment”. While the answers looked promising, none of them worked in Astro with the default Markdown configuration.

Using <img> directly doens’t work, because Astro does image optimisation. Fair enough, probably.

One of the answers from 2009 by a user called “raphox” prompted me to try nesting Markdown code to include an image within HTML code. With a bit of experimentation, I noticed that formatting the image suddenly worked. It took me a bit longer to figure out what exactly works and what doesn’t.

It found it pretty surpirsing exactly which combination of HTML and Markdown works in Astro: You have to wrap the image in a <span> element. The code doesn’t work if you try to wrap the image in a <p> or <div> element.

So, putting an image between <span> and </span> works and you can use any standard CSS properties to control sizing, positioning or anything else:

Code:

<span style="display:block; float: right; margin-left: 1em; margin-bottom: 1em; width: 200px; height: 200px; border: 2px solid #0000ff;">
![Test Image within span](../../assets/images/content/inspiration/2023-05-29_craiyon_nps_earned_growth_happy_customers_05.webp)
</span>

It feels a bit hacky, but it’s simple, doesn’t need any plugin and gives me the flexibility I want when adding images to text. I works with or without line breaks, I generally prefer to write it with line breaks, as that makes it easier to read and edit.

(Of course, I’m aware that it could probably break at any time. But right now it works.)

What I expected to work, putting an image within a block-level HTML element such as between <div> and </div> didn’t work:

Code:

<div style="width: 200px; height: 200px;">
![Test Image within div](../../assets/images/content/inspiration/2023-05-29_craiyon_nps_earned_growth_happy_customers_05.webp)
</div>

I also tried to have all code in a single line, it still didn’t work.

I am not entirely sure why it works with <span>, likely because the Markdown parser does something smart with some tags but not with others. Maybe I don’t even want to know. For the moment, I’m just happy that I can achieve what I want with basic Markdown and a little bit of HTML & CSS - without losing useful Markdown features like automated image optimisation (not scaling, but I can live with that).

Completely unrelated, but something I discovered while writing this. The Tailwind Typography plugin thinks it’s a good idea to add backticks when displaying <code> blocks. I found on GitHub how to change this. Everything looks much better without!

(Prompt for Craiyon V3 to generate the header image: “Formatting images in Markdown with HTML & CSS: <span>![Image](path)</span>” / Style: Drawing.)