Change Behaviour of the Markdownify Filter

I’m currently trying to create an art blog which naturally involves a lot of images. I love using jekyll and its ability to convert markdown into html using the markdownify liquid tag.

In an effort to make my website more responsive I am also using the plugin jekyll_picture_tag. For those not familiar it uses

{%picture path/to/picture %}

and will automatically generate all the different size images and the html to set up the scrset.

What I would like to be able to do is just include an image in the blog post in normal markdown syntax, but when passed through the markdownify filter, processes it as if it is the snippet above (or semantically similar html which I can write myself) - currently, I just have to have the liquid snippet in the middle of my markdown file so I cannot preview the file by itself with all the images shown.

I’m not hugely familiar with Ruby (though can pick it up) and very much have taught my self web development for this project, but I was wandering where the markdownify (and other liquid filters) are defined so that I can go in and change the behaviour?

Hi maybe I can help. I have experience with Jekyll resizing.

Are you saying you want:


To turn into this

{% picture path/to/picture %}

And render it?

That seems like a strange flow to change the fundamental markdown behavior to act like a tag which you have access to by itself.

What’s the advantage? So that you can preview the image in plain .md on github?

For interest I use a fork or jekyll-resize which is like the jekyll picture tag.

The resize tag is used there for a thumbnail

And href is used below for linking to the full size image.

It is for a template of an art gallery

It is a very minor thing but yes that is what I am after and its largely so I can have a ‘pure’ markdown file that that I can preview the image in which jekyll then converts into the exact html that I want rather than having to use liquid tags that add HTML to my markdown file and then markdownifys it.

I also notice that when I use the liquid stage rather than the .md syntax the HTML that is produced wraps the image in a p tag which can also be a faff.

None of this is restrictive by any means and I can make pages how I want them using the current set up. I just wasn’t sure if there was an easy way to access what the filters do and change their behaviour and it just felt like it could have been a simple quality of life improvement for a website I hope to contribute to for some time to come.

What about doing this all over? It will keep the preview as markdown doesn’t handle capture. It just takes a few lines and is verbose. Note use of empty lines as well but you can remove them if that works.

{% capture image %}

![alt text](/foo.png)

{% endcapture %}
{{ image | markdownify }}

Also note that regardless of the approach you use, that typically you want to so this in your image.

![alt text]({{ '/assets/foo.png' | relative_url }})

So that your image works on

Which also means it won’t work in a preview markdown

So this you’d have to restrict yourself to a user site with no sub path. Or put the subpath in URL

E.g. /repo-name/assets/foo.png

Which is not elegant and is an anti pattern for jekyll. However it will get the behavior your want.

Also if you want to skip markdownify hacks or capture altogether you can do that.


And it will preview in markdown and show on a jekyll gh pages site. You just have to do a find an replace if you rename the repo.

Personally I don’t care about preview in markdown. I use a local jekyll server to check the page.

And if I can worried about a broken image link I use the link tag as it will abort your build on a missing file

![]({{ site.baseurl }}{% link assets/foo.png %}

Note you need to use baseurl here because you can’t pipe the link through relative_url.

Check out this gist for a simple Jekyll plugin. Essentially it takes Markdown images and rewrites to the {% picture %} tag.

I haven’t used it in years so it might need some minor modifications, but should at least get you started.

Thanks for sharing the gist. Looks like a nice solution.
Reminder for OP that custom plugins won’t work on gh pages without GH Actions. Whether installed or added directly to plugins folder.

Exactly what I am looking for, appreciate the gist

MichaelCurrin also appreciate your comments as well, I was not familiar with actions so that may also save me some additional faff in my work flow