How to handle URLs in HTML in blog posts

[lilacpixel]

I've read quite a few blog posts and GitHub discussions on handling media URLs in HTML, trying to figure out a solution for a problem I'm having. It's known that MkDocs ignores embedded HTML during processing, so, say, this image would have its URL altered to reflect the correct folder structure after building:

![An image](img/test_image.jpg)

While this image would be left untouched:

<img src="img/test_image.jpg" alt="An image">

(For some reason, only this type of relative URL seems to work, and paths like ../img/test_image.jpg don't get updated, even in Markdown. I still haven't figured that one out, but that's also not my main question.)

The prevailing solution seems to be to adjust any paths in your HTML to point to where the image will be after building. This is fine for media embedded in pages that will only ever be served at one location, but it falls apart when dealing with Material's blog plugin, where the same post can be seen here…

https://example.com/blog

… or here…

https://example.com/blog/page/2

… or here.

https://example.com/blog/2025/01/01/post

And so on.

Obviously, there is no relative URL structure that will satisfy all of these. Using Markdown is an option in the case of the image example above, but I'm working with things like <audio> and <video>, which have no Markdown equivalents. Is there any reasonable solution that will work for these, or is this more or less unfixable pending a bigger overhaul of the MkDocs build process?

[kamilkrzyskow]

Hi @lilacpixel,
yes, relative path lookup is done in Markdown, and HTML isn't parsed, and used as-is. Maybe there would be a way to write a Markdown Extension that would generate the video HTML tag and it would hook up with the rest of the MkDocs extension ecosystem.

There is this extension, but I doubt that it does parse paths 🤔
https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/html/

Also in this context, the blog plugin also adds another layer of page management, so the extension might to support both MkDocs and the Blog plugin if there is some inconsistency.

A quick fix that I see would be to use an absolute path src="/path/to/video.mp4" or a placeholder that would be dynamically adjusted into the absolute path via hook

---

For some reason, only this type of relative URL seems to work, and paths like ../img/test_image.jpg don't get updated, even in Markdown. I still haven't figured that one out, but that's also not my main question.)

So this could be a Blog bug, but without an example it's hard to tell. Image Markdown structures should point to the relative path of the filesystem path. If the file isn't found, then the path is left as-is, and there should be a warning. The final HTML path needs an additional ../ because there is a top-level directory in the URL, it ends with /.