Relative URLS in embedded HTML are not rewritten to account for directory URLs

[daviewales]

Suppose I have the following directory structure:

images/example.jpg
page.md

If I want to include example.jpg in page.md using Markdown syntax, I can do the following:

![example image](images/example.jpg)

So far so good. If I browse the markdown file on GitHub, the relative URL will work, and will display the image in the GitHub preview.
If I render the docs as HTML and publish them, then the real directory structure will be modified to use directory URLs with index.html, but the generated URLs in the HTML pages will automatically be updated to account for this.

e.g. The generated structure is:

images/example.jpg
page/index.html

And index.html accounts for this new structure:

<img alt="example image" src="../images/example.jpg">

This is all good, and expected.

Now, suppose for some reason I need to include some inline HTML in my Markdown, and the inline HTML includes a relative link.
I would expect to still be able to use the same relative URL syntax as in the Markdown above, and that MkDocs would update this to point to the correct location based on the directory URL structure. However, it appears that MkDocs doesn't touch links in embedded HTML at all, even if they are relative URLs.

For example, suppose my original page.md was the following:

<figure>
  <img src="images/example.jpg">
  <figcaption>Example Image</figcaption>
</figure>

This won't work, as MkDocs will leave the image URL untouched, which breaks with the generated directory URL structure.
Instead, I need to account for the rendered structure in my source file:

<figure>
  <img src="../images/example.jpg">
  <figcaption>Example Image</figcaption>
</figure>

However, this breaks the Markdown previews on GitHub, and is somewhat confusing when you are used to working with the auto-rewritten Markdown URLs.

Is this the intended behaviour?
Would it be possible to automatically rewrite relative URLs in embedded HTML the same as is currently done for Markdown URLs?

[pawamoy]

I believe MkDocs injects a Markdown extension during the Markdown-to-HTML rendering step in order to detect and fix links to assets (pages, images, CSS, etc.). Such raw HTML isn't "seen" by this extension, for technical reasons (they are "stashed" and added as-is to the HTML final result). I think @oprypin managed to detect raw HTML headings though (for other purposes), so it might be possible to detect and fix raw HTML links.