configuring image filepaths correctly in mkdocs

Question

I have an issue with MkDocs not being able to find my images. The images are in a subfolder, called microsatsFigures, in my docs folder. So my /docs folder contains index.md, traces.md and the folder microsatsFigures which has the images. In my Markdown file traces.md I am using html syntax for the images so the path to the image is:

<img src="microsatsFigures/Figure_setLoci.png"/>

This works perfectly in markdown editors that I am using (Typora and Macdown), and the image is displayed no problem. However mkdocs can't find the image - I get

WARNING - [15:02:53] "GET /traces/microsatsFigures/Figure_setLoci.png HTTP/1.1" code 404

There is no "traces" folder, so its not surprising it cannot find the image.

If I change the image path to <img src="/microsatsFigures/Figure_setLoci.png">, it works in Mkdocs but not in the markdown editor.

I don't understand why mkdocs can't use the relative path microsatsFigures/Figure_setLoci.png, and why it requires a / in front. And why does it look for the image in a /traces folder that does not exist if I don't use the /?

I'm using html because I need additional formatting on the images, but the same issue occurs with standard markdown image syntax.

Is there something I need to configure in MkDocs to get it to recognise the path in the same way that the markdown editors do? I'd really like to be able to preview my images in the markdown editing tools I'm using but at the moment I can either get it to work in MkDocs or the editor, but not both.

Answer 1

@Chris's answer is correct. However, if you really need links to be in raw HTML, then you could set the use_directory_urls config option to False. Then MkDocs will not change the URL/location of the rendered file from the source file and the relative links within raw HTML will work on both the rendered document and your Markdown editor.

By the way, this is why you need to make the links absolute (add a / to the beginning of the URL). The use_directory_urls option is altering the location of the rendered document so that the relative URL to your image is no longer correct. When using Markdown links, MkDocs automatically adjusts relative links for this. But it ignores links within raw HTML. Disabling use_directory_urls avoids this issue completely.