mkdocs: Image paths can break when deploying to gh-pages

tl;dr

Regardless of whether you’re using markdown or HTML

• if you are importing an image in your index.md, use ./img/image.svg;
• if, in another page, use ../img/image.svg

---

I’m new in mkdocs. However, I’m excited about how it make easier my work! Thanks! I hope to contribute to future users that will face that problem. I have made some tests of importing images by using markdown syntax and raw HTML.

Let’s suppose a project like this:

/docs/
  |-- img/
      |-- image.svg   # /docs/img/image.svg 
  |-- index.md        # /docs/index.md
  |--page-a.md        # /docs/page-a.md

Importing image.svg into index.md, we have the following possibilities:

method	at localhost (https://localhost:8000/)	at github page (https://user.github.io/project/)
	✔️	❌
	✔️	✔️
	✔️	❌
	✔️	✔️
<img src="../img/image.svg" />	✔️	❌
<img src="./img/image.svg" />	✔️	✔️
<img src="/img/image.svg" />	✔️	❌
<img src="img/image.svg" />	✔️	✔️

However, importing image.svg into page-a.md:

method	at localhost (https://localhost:8000/page-a/)	at github page (https://user.github.io/project/page-a)
	✔️	✔️
	✔️	✔️
	✔️	❌
	✔️	✔️
<img src="../img/image.svg" />	✔️	✔️
<img src="./img/image.svg" />	❌ :	❌ :
<img src="/img/image.svg" />	✔️	❌
<img src="img/image.svg" />	❌ :	❌

I suppose that difference between markdown and raw HTML became from the fact that “When including internal links within raw HTML, you will need to manually format the link appropriately for the rendered document.” (see more here).

However, concerning to difference between localhost and github pages, I don’t know the reason.

1. Let's say you want to store your images in an `img` folder inside the root of your docs

2. Embed an image like this: `![](/img/image.png)`

3. test in a local environment -> works fine

4. deploy to gh-pages -> missing image

The generated HTML will link to the image like this: <p><img alt="" src="/img/image.png" /></p>

But the image will actually be at https://username.github.io/repo-name/img/image.png and it won’t show up.

This entire issue can be avoided (and most likely is by a lot of people) by using relative paths. Still worth considering if maybe the repo’s name should automatically added before the image URL, if it’s an absolute path.

config: mkdocs 1.0.04, windows10

Thanks @devakker, saved a lot of debugging!! 😃

I’m using relative urls, but the images are still not working. What is the ![]( ) that people keep talking about. I’ve not encountered this before.

I am not a fan of web development and never came across this special …/path notation.

This is not specific to web development and is not “special,” but is a standard feature at the system level. For example, see Absolute and Relative Pathnames in UNIX, which was one of the top results in a quick search (perhaps not the best explanation, but the first I found with little effort).

In any event, I’m glad to have helped.

Okay, thanks I will look into it.

Now that I read the docs more thoroughly, it does seem clearer that relative paths are the way to go. This wasn’t clear for me before, and the paste image vscode happened to be configured on my machine to use absolute paths. Now I managed to reconfigure it to use relative paths so it’s all good.

Maybe we should add an explicit warning in the documentation about the usage of absolute paths not being supported and recommended. I would be happy to do a PR if you think it’s a good idea.

This entire issue can be avoided … by using relative paths.

For consistent results the documentation actually points out that relative paths are required. You may or may not get things to work correctly with absolute paths and use them at your own risk. In fact, they only work if the mkDocs root and server root are the same directory. The reason for this is that relative paths are adjusted by MkDocs to ensure they are always relative to the page, However, absolute paths are not modified at all. In other words, absolute paths do not get adjusted based on the server environment.

We do not adjust absolute URLs as some users actually want/need that behavior. For example, some users may want to link to something hosted on the same sever, but outside of MkDocs. Suppose the MkDocs site was at http://example.com/docs/ but they wanted to link to http://example.com/foo/bar/. They could simply include a link to /foo/bar and it would work correctly. However, if we treated the link as an internal link, we would either break the link or raise an error when trying to verify it, neither if which is desired. Therefor all internal links must be relative links to be verified and auto-adjusted as necessary.

Finally, note that if you are in an environment where the MkDocs root directory is a subdirectory of the server root, then you should set the site_url config setting to include the subdirectory. For example:

site_url: https://username.github.io/repo-name/

The local dev server will then use that subdirectory, which will help to ensure consistent behavior between the local dev server and your production server.

In conclusion, the problem is user error, not a bug. Two things should be done to correct the problem:

1. For all internal links, use relative URLs: ![](img/image.png)
2. Properly define site_url to include the subdirectory so that it points at the MkDocs’ root.

i am using the following structure for my docs/ folder:

To link from docs/content/doc1.md to docs/img/pic1_for_doc1.png the path would be ../img/pic1_for_doc1.png. Standard relative path stuff.

As a reminder, MkDocs is a tool for generating technical documentation. We assume users have a technical background. Additionally, as it is a command line tool, we assume that users understand the basis of the command line, which includes an understanding of relative paths.