Image paths can break when deploying to gh-pages

[devakker]

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

[waylan]

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.

[devakker]

Thanks for taking a look at this. I have a follow-up question:

I have site_url set up, the line in my mkdocs.yml looks like this:

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

If I use mkdocs serve should my base URL look like http://127.0.0.1:8000/repo-name/ ?

[waylan]

If I use mkdocs serve should my base URL look like http://127.0.0.1:8000/repo-name/ ?

Sorry, my last comment was slightly misleading. Actually, including the subdir in site_url causes a production build to act slightly differently. It doesn't effect the dev build (used with the the serve command) at all. In retrospect, I suspect your specific issue is not related to site_url at all. However, you should still have it correctly set as it will avoid a few other possible bugs. Feel free to search the closed issues if your interested or start with #1318.

[devakker]

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.

[waylan]

I'm always happy to review PRs.

[root-ansh]

i am using image links exactly as @devakker described, but my yml is generating links like this : https://username.github.io/img/image.png (i.e not including sitename at all, causing error. What could be the possible issue?
(PS: please ignore my stupid comments)
my mkdocs.yml:

site_name: Curioustools # Website name(comes on top left in nav bar)
site_description: Google certified Associate Android Dev #browser tab tooltip text
site_author: Ansh Sachdeva(root-ansh) #don't know where does it shows
site_url: https://root-ansh.github.io/curioustools/  # used for using local images in production

#Header
#repo_name: 'root-ansh/curioustools'
#repo_url: 'https://github.com/root-ansh/curioustools'
#tabs:{a,b,c} X # Tabs are generated automatically using nav's topmost division and theme's  extras -tabs: true feature

#Footer
extra:
  social:
    - type: 'github'
      link: 'https://github.com/root-ansh'
    - type: 'twitter'
      link: 'https://twitter.com/root_ansh'
    - type: 'linkedin'
      link: 'https://linkedin.com/in/anshsachdevaprofessional/'

copyright: Copyright &copy; 2019 <a href="https://www.linkedin.com/in/anshsachdevaprofessional/">Ansh Sachdeva</a>

#Theming
theme:
    name: material
    palette:
        primary: 'white'
        accent: 'green'
        #links_color : 'green' #todo, this is not the correct solution
        
    logo: img/logo/logo.svg
    favicon: 'assets/images/favicon.ico'

    feature:
        tabs: true    

    language: 'en'    
    extra:
        search:
            language: 'en'
            tokenizer: '[\s\-\.]+'
    
    #custom_dir: no_toc #not working
        
    #toc:
        # disable: true # todo, this is not working. expected this to remove table of contents
#extra_css:
#    - 'stylesheets/extra.css' # for disabling toc # not working

# Extensions
markdown_extensions:
  - markdown.extensions.admonition
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.def_list
  - markdown.extensions.footnotes
  - markdown.extensions.meta
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_svg
  - pymdownx.inlinehilite
  - pymdownx.keys
  
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist:
      custom_checkbox: true
  - pymdownx.tilde

        

nav:
    - About Me: index.md
    
    - Education Details:
        - Introduction: tab_edu/edu_details.md
        
    - Work Experience: 
        - Introduction: tab_work_exp/work_exp.md

    - Portfolio:
        - Introduction: tab_projects/project_summary.md
        - SelfNotes : tab_projects/project_selfnotes.md

    - Blogs:
        - Introduction : tab_blogs/blog_summary.md
        - Android : 
            - tab_blogs/android/world_of_videos.md
            - Misc:    
                - tab_blogs/android/enums_and_intDefs.md
        - Web:
            - Mkdocs:
                - tab_blogs/web/basic_syntax.md
            
        #- Misc:
        

[waylan]

i am using image links exactly as @devakker described,

As I explained, this is the wrong way to format your links.

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.

[root-ansh]

@waylan i think i am confused about the concept of relative and absolute paths. To clarify, My markdown files import images as ![text](/img/picname.png) or <img src="/img/picname.png"> . from what i know, this is a relative path, right? and as your conclusion here says, this is the correct way to do it?

[waylan]

No a relative path does not start with a slash. Your path needs to be 'relative' to the current file location.

[root-ansh]

@waylan how am i supposed yo maintain a clean repository if i have to make picture location relative to "current folder" and not "parent folder" ? currently , i am using the following structure for my docs/ folder:

I try to access them via docs/img/picname.png but couldn't , even though it is showing a fine output in mkdocs serve mode .
And from what i can understand, you are proposing a structure like this :

I even feel the end location is being successfully identified i.e the pictures present in the docs/img/ folder, like docs/img/picname.png are correctly showing as 127.0.0.1:8000/img/picname.png in the local server, but is not getting translated to username@github.io/reponame/img/picname.png but rather username@github.io/img/picname.png (i.e not refrencing the repo name in the url).

I am guessing its my repo problem. Should i create a new issue?

[waylan]

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.

[root-ansh]

Oops😅, I apologize. I am not a fan of web development and never came across this special ../path notation. Thank you , your correction helped me get over the problem i have been struck on for last 2 days . And also, thank you so much for this amazing project, it helped me setting up a little site about myself (hehe, not the exact usage of a "documentation" generator, but i am eagerly waiting for an mk-blogs, if that's a possibility😄 )

[waylan]

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.

[pagarevijayy]

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!! :)

[danielpcampagna]

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.

[waylan]

@danielpcampagna there are two separate reasons why various of those URLs failed.

1. You did not take into account the use_directory_urls config setting. When set to True (the default), the page page-a.md would get rendered to page-a/index.html which would change the relative path to your image file. Of course, index.md would get rendered to index.html, which explains the difference between those to pages.

   Note that when using Markdown links, MkDocs adjusts relative links to account for this. However, Markdown, and by extension MkDocs, ignores raw HTML links. Therefore they need to be custom crafted to account for this. The downside is that then they don't work in your text editor or when browsing the source of GitHub.

   An easy workaround is to set use_directory_urls to False. This gives you consistent relative URLs between your source and the rendered site. Of course, all your pages will have .html in the URLs now. But that is probably worth it is you insist on using raw HTML for internal links.

2. The localhost server root is the same as the MkDocs root; namely /. However, the GitHub pages server root is / while the mkdocs root is at /project/. Therefore, when using absolute URLs (URLs which begin with /) you need to include /project/ when serving from GitHub pages, but not when serving from the local server. MkDocs does not account for this and that is why the docs suggest that you never use absolute URLs for internal links. This is easily avoided by only ever using relative links.

[ghost]

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.

[waylan]

@lindsayfowler ![]( ) is the Markdown syntax for linking to images as documented.