2

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.

Hilary Miller
  • 31
  • 1
  • 2

2 Answers2

2

I suspect this will work as expected if you use Markdown instead of HTML:

![Alt Text](microsatsFigures/Figure_setLoci.png)

Here is what the documentation says about linking to images from :

Markdown allows document authors to fall back to raw HTML when the Markdown syntax does not meets the author's needs. MkDocs does not limit Markdown in this regard. However, as all raw HTML is ignored by the Markdown parser, MkDocs is not able to validate or convert links contained in raw HTML. When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document.

Why doesn't it work with raw HTML?

Assuming MkDocs generates URLs like https://your-site.tld/traces/, your browser sees that as a directory. A link to some-image.png will be interpreted as https://your-site.tld/traces/some-image.png.

ChrisGPT was on strike
  • 127,765
  • 105
  • 273
  • 257
2

@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_direstory_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_direstory_urls avoids this issue completely.

Waylan
  • 37,164
  • 12
  • 83
  • 109