Relative links in pages below the top-level document folder point to the wrong path

[jdhoek]

Relative image links in pages below the top-level document folder seem to point to the wrong path.

Reproduction

I've created a minimal reproduction case:
https://github.com/jdhoek/mkdocs-test-relative-image-links

The reproduction case contains this file structure:

├── docs
│   ├── index.md
│   ├── subdir
│   │   ├── sub.md
│   │   └── sub.png
│   └── toplevel.png
└── mkdocs.yml

mkdocs serve and mkdocs build correctly process the Markdown files in the top-level folder docs_dir, but with the Markdown file in the sub-folder the relative image links are broken.

[tomchristie]

Probably same as #77 but this is more helpful.

[jdhoek]

I wasn't sure if #77 was the exact same issue. Thanks for referencing it.

[d0ugal]

This is a great report, thanks very much.

Things gets a bit confusing as, I think, we have links in three different scenarios.

• Links to markdown (as far as I'm aware, no known issues)
• Links to static assets like images (this issue)
• Either of the above on a "static page" like the 404.html which could be returned under many paths. (this is probably relative url's can cause bad links #77).

The first two vary because we move the location of markdown files (my/document.md becomes my/document/index.html and is thus one level deeper). So, these issues are probably subtly different but I expect a fix will need to take all the above into account.

@jdhoek Just to check, did you test this against the latest release or via git master? There was some fairly recent fixes for images, but I can't remember if it made the last release or not :)

[d0ugal]

... I just confirmed, it is still an issue with the latest dev version.

[d0ugal]

I can't see an obvious reason, but the broken image path is coming out as ../../sub.png when it should be ../sub.png.

[d0ugal]

Gah, I see the issue with images. It comes down to my miss-understanding of the url rewriting when I added support for them. it is actually a coincidence that any of these work. 😳

Clearly the tests I added for this are completely bogus. I'll look into a real fix.

Using create_media_urls here is completely wrong. https://github.com/tomchristie/mkdocs/blob/aaf344630f4732ae58d1da28b25d0c02bd8d56b9/mkdocs/relative_path_ext.py#L59

[jdhoek]

@d0ugal
My apologies, I should have mentioned the version. I am using the latest stable release from PyPI; v0.11.1.

[Mopster]

I came across this problem today, any eta on v0.12 ? :-) Currently I have to choose between working images in the GitHub repo or on the generated site :-)

[d0ugal]

@Mopster The 0.12.0 milestone is here. I've got it down to just a smallish number of bugs. https://github.com/mkdocs/mkdocs/milestones/0.12.0 - I am hoping to do it this weekend, but no guarantees ;)

[Mopster]

great! gonna show it off to the office today ;-)

[Atlas-Night-Out]

I also have these issues been trying loads of different ways to get images to show up on GitHub, with no luck. They work on a website domain and also in MKdocs server too just no luck at all in Github. Can anyone help me with this or is it not possible?

[lambdamusic]

I was able to get this working by using a relative path. Eg in sub.md:

![Screenshot](../../img/image.jpg)

Obviously not ideal cause each time one needs to remember the file location relative to the img folder.. but it works.

[alex20465]

I have the same issue, the solution is clear... just change the path.

BUT ! the relative paths markdown -> assets (./xy) is rendered correctly by almost every platform (github, gitea, vscode etc.)

once you copy a document structure to mkdocs, we have to change all paths basically to correct into "wrong" to the other platforms.

this quite sucks since the assets relative path is current to the markdown BUT incorrect after build.

mkdocs needs a assets-uri-resolver strategy configuration.

[kuchaguangjie]

Does this answer on SO fix your problem ?