1. Bitbucket
  2. Public Issue Tracker
  3. master
  4. Issues


Issue #6589 duplicate

Markdown relative link to image and other readme does not work

Georgios Petrou
created an issue

I have the following folder structure.


Inside Folder1/Readme.md I have:


Shouldn't this work?

Comments (67)

  1. Erik van Zijst staff
    • changed status to open

    No, that will not work because your readme is rendered on your repo's landing page, which typically is:


    and so your markdown link produces the img URL:


    Now that's an invalid URL. Well, not invalid, but it points to something that lies outside of your namespace and doesn't exist.

    You might be tempted to fix this by changing your markdown image to:


    while this should work for the readme displayed on your repo's landing page, it will break when viewing the readme on the source browser (which lives at a different base URL).

    The conclusion is that you will need to use an absolute URL. Here's a readme of one of my own repos that includes a screenshot:


  2. Edouard Lavery Plante


    I disagree that this issue is invalid. Bitbucket's markdown support is very good and we started using it to document our projects.

    However, links between markdown files are very useful for big projects.

    Using absolute URLs prevents us from working with the markdown files locally, which is annoying.

    It's also incompatible with the git architecture which permits us to push the same repo to multiple servers and problematic when dealing with branches and specific commits.

    Furthermore, GitHub implements relative links : https://github.com/blog/1395-relative-links-in-markup-files and this syntax documentation states that markdown supports relative URLs http://daringfireball.net/projects/markdown/syntax.

    Bitbucket should rewrite relative URLs so that they work in the context of bitbucket, not the other way around.

    Thanks and keep up the good work !


  3. Alex Bahouth

    Err, this isn't a reasonable solution to use full URLs. Again, if someone is browsing the files outside of bitbucket, this completely breaks the ability to create documentation.

    Echoing what Eduoard said- please fix it so that Bitbucket rewrites relative URLs in the context of bitbucket, not the other way around.

    Thanks, Alex

  4. Eric Anderson

    I strongly agree with Edouard and Alex: Relative paths are the cleanest, best way to link files together when the whole directory structure (or repo) might be moved around. Having these work from the README would be very good.

  5. Anonymous

    Same issue as others mentioned. Relative URLs do not work when the README is displayed in the directory/overview. But works if I am in the README file.

  6. kristom

    I agree with others that absolute URLs aren't an option.

    Also Atlassian self claims on https://confluence.atlassian.com/display/BITBUCKET/Display+README+text+on+the+overview following:

    "We support Python-Markdown. Please note, we don't support arbitrary HTML in Markdown, for example <table> tags. Instead, we use safe mode. Safe mode requires that you replace, remove, or escape HTML tags appropriately."

    Following Python-Markdown which is based almost 100% (some minor changes) of John Gruber's standard and that one claims on basic syntax very clearly usage of relative paths/links (see: http://daringfireball.net/projects/markdown/syntax#img).

    This is also anyone's expectation who has used Markdown for documentations/writings.

    Could please not ignore this and rather support expectation from your customers.

    Thanks in advance!

  7. David Vins

    Erik, when on Earth is someone going to be assigned to #6315? It has been more than a year, it has 250+ votes, and at this point is the source of a considerable amount of frustration among users.

  8. Tobias Preuss

    Is this still an issue? The README.md is in the root of my project. There is an img/pic.png which I want to include. I tried these:

    • ./img/pic.png
    • /img/pic.png
    • img/pic.png

    None works on Bitbucket.

  9. Software Frameworks

    Please don't be gutless. Fix this problem.

    Motivated by your founder, Mike Cannon-Brookes (please watch this: http://www.youtube.com/watch?v=FZPoahbOmgQ), the lack of relative links for images is a serious deficiency that needs an immediate fix.

    This is a really important feature to users everywhere - as the year-and-a-half series of posts (sadly, with no replies from Atlassian) evidences, we need this in order to construct meaningful README files for the projects you wish to host. With so much time having passed since the issue was originally brought to your attention, to not only fail to implement it, but furthermore utterly neglect to update the community - or even suggest that it's on the roadmap - is completely unacceptable.

    As GitHub fully supports this functionality, there's little doubt that BitBucket has disappointed many users over this, and rightly so. More dumbfounding than the lack of this basic functionality is Atlassian's spectacular failure to communicate with its dedicated users. Truly a disappointing situation. Don't be gutless - fix this problem.

  10. Greg Meece

    I guess I'll pile on as well. I use several Atlassian products at work (Jira, Confluence, plus Sourcetree - both at work as well as personal projects). I host a personal project on Bitbucket (which I really like BTW), but the lack of relative file support is really irritating. I will not be able to point a client to the repo so they can follow along with Markdown documents.

    I realize there are probably challenges with this, but it seems like it's not rocket science.

  11. Jimmy Aguilar Mena

    More than a year the people complaining and they don't care... It is not so complicated!!!! Gitgub and Gitlab have already implemented this, why why!!! I think they don't really care.

  12. Justin Forest

    Maurice, this is simple. Atlassian is a commercial entity, they earn money. Obviously people who make decisions there don't see how wasting 1 developer hour on this issue will bring them more money. If all +1 people from this thread would stop buying premium services from Atlassian, the feature would be implemented next day. However, I doubt that any one does really buy anything, or cares enough to go away. Anyway, it's a free market, go to Github if it has the features you need. Or get a job at Atlassian, fix the issue, then quit.

    Besides, a cleaner documentation? For local use? What do you do locally with Markdown files, render them to HTML? What's the problem with using, like, sed to fix the links? And a hook to prevent committing wrong links to the repo? No problem.

  13. Iñaki Baz Castillo

    Well, people making decisions may interpret that this feature gives no money to them, but at least in my case I would never buy a Bitbucket commercial plan if that means than migrating README and doc files from/to Github requires me to mangle the links.

  14. John Schank

    Hold up... There is a wiki, which is a git repository, which I can clone, and I can use images in the wiki, but I cannot use them in my readme. Even though both wiki and readme use markdown.

    Am I insane, or can I safely assume that the wiki is worthless and that images will not work there either?

  15. David Jones

    It is possible to use images and links to other documents in the wiki, README, and other markdown files, but you have to format them with absolute paths based on the repository name, and include the branch name. It can be done like this:

    ![Some Image I want to display](/bitbucketuserororgname/repositoryname/raw/master/path/to/image/image.png)


    [Some Link to another Markdown file](/bitbucketuserororgname/repositoryname/raw/master/path/to/markdownfile/somefile.md)

    There wasn't an obvious way to get that path, and there will be issues if you rename your account or repository, or you are looking at a prior version of the README, then it's going to show the version of the image on the master branch and not on the commit or branch you are looking at.

    In short, it is doable, but not easily, and there are potential pitfalls depending on your workflow. I'm not defending that they haven't implemented relative links, just pointing out that it is possible.

    I would really like repository relative link and image support in markdown file display also, but I figured it would be useful to show how you could do it today.

  16. Richard Ambler

    I think that the idea is to encourage developers to have a bare minimum description in the readme file associated with a project and to set up a wiki for the documentation (and Bitbucket wikis do support relative links). I think that it is a good idea to separate the documentation from the code but I agree that it can be a bit frustrating, especially when, say, importing a project from Github, not to support relative links.

  17. Matthias Viranyi

    We shall not argue about the meaning of relative URLs and whether it is good to have them. I think we all agree on It'd be good to have 'em. Separation of README and documentation doesn't fall or rise with this feature.

    The renderer (interpreter or compiler) should take care of relative URLs, which really isn't that hard. I used relative URLs for documentation 15 years ago, why should I stop now?

  18. Tom Roche

    @Richard Ambler: 'Bitbucket wikis do support relative links'

    Not particularly well/completely: for empirical results, see my reST link-test project, e.g., its wiki's Home. Among the current (as of 27 Apr 2015) inconsistencies: it can display an image in the project's downloads, but not in the project's ./images folder/subdir.

    @Richard Ambler: 'developers [should] have a bare minimum description in the [project's] readme and [and instead use] a wiki for the documentation'

    That's what I usually do: see, e.g., this project's README.md/overview. Interestingly, currently,

    • in the README.rst/overview--i.e., in reST--true relative links to the wiki (e.g., ./wiki/Home) now work.
    • in the README.md/overview--i.e., in Markdown--a true relative link to the wiki (./wiki/Home) fails, but a "Bitbucket-style," pseudo-relative link of the form project_name/wiki/Home works.

    I'm pretty sure neither worked until recently--if so, good to see that fixed. Either way, ISTM interesting that (IIUC) a main-project-repository file can relative-link to a wiki-repository file, though not vv.

    My reST link-test project really should also

    1. create a separate ./wiki/images folder/subdir
    2. test relative-links to that from wikipages

    Your pull requests are welcome! otherwise I'll get to it when ...

    And 1 more question: why must a project's wiki be in a separate repository from the rest of the project?

    And ++1 more question: has someone already made an issue about that?

  19. Tom Roche

    @John Schank: 'It is important to note that a pseudo-relative link, such as you describe, will NOT work on a local filesystem.'

    Agreed. The points I seek to make are

    1. The bitbucketeers seem to believe that link-resolution is a separate issue from markup rendering--at least, they have marked (e.g.--I could have this reversed) reST relative-linking issues as duplicates of Markdown relative-linking issues. However ISTM at present link-resolution behavior differs by markup.
    2. There also seems to be difference between how relative links resolve in a project's wikipages (i.e., files in or below .../project_name/wiki/) and how they resolve in "the main project" (i.e., files {in or below .../project_name/ && !in or below .../project_name/wiki/}).
    3. I sense "code smell" in the pseudo-relative link behavior: it feels like a kludge someone stuck in the code somewhere to temporarily cover some testcase.

    @John Schank: 'I want to see my images rendered even if I open the readme.md in a markdown editor on my local machine, as well as have them rendered when hosted on bitbucket.'

    Ditto. Or if locally rendered by a tool like pandoc or restview.

    @John Schank: 'GitLab, and I believe GitHub can both do this.'

    Well, that's an empirical question, which should be systematically tested. It certainly was not working recently with GitLab-as-a-service, but I have not retested.

  20. Tom Roche

    @Dominik Kroutvar: 'please give some examples or link the document here how to use relative links for images etc'

    You can see what's currently working in my project=rst_link_test. For images, these links to files in a top-level project folder=.../rst_link_test/images/ (i.e., in a subdir just beneath the project root) currently work from an overview README:

    1. /images/Jen_Sorensen_PandP-poster-ForWeb.png
    2. ./images/Jen_Sorensen_PandP-poster-ForWeb.png
    3. images/Jen_Sorensen_PandP-poster-ForWeb.png

    The older "Bitbucket-style" pseudo-relative links no longer work, nor do "relative-style" links to a file in one's Downloads, but the above "truly-relative" links work ... from a file (such as one's README) that is also in the project repo.

    Interestingly (at least to me :-), when linking from a wikipage to an image, only links to an image in the project's Downloads seem to work, and only with the following syntax: ../downloads/Jen_Sorensen_PandP-poster-ForWeb.png

  21. Tom Roche

    Àpropos of this issue, I'd appreciate votes for the newly created FR#=11294 regarding relative-linking from wikipages to files in its project's repo. Note that I'm aware that BB currently intends to keep wiki repositories separate from their project's repo. However, currently-supported behavior seems to demonstrate that there is no technical impediment preventing a wikipage from relative-linking to a file in its project's repo--but currently only relative-links from a wikipage to a file in its project's Downloads (e.g., here) seem to work.

  22. russells-rocksauce

    In case someone else comes across the same issue I did, it's important to make sure:

    1. Don't use any spaces in image or directory names. For example:

    ![](images/app screens/screen 10.png)

    should become


    1. Sub-folders can be used for other md documents. Again, I recommend replacing spacing with dashed even in folders that only contain md or other files.

    2. Not sure about this, but the starting document might need to be named README.md, and images might need to be in a top-level folder named "images" in the same directory as the README.md file.

    Finally, please refresh your page when you see a broken image link. I noticed some images would load and others were not even though they were in the same format. A refresh caused the broken images to load correctly. Don't know what causes that.

  23. Alenn

    Hello, I would like to make a wiki page with links to my repository. I gave up setting up one picture from repository and I uploaded it to imgur and place it to new .md in wiki, but what about repositoryfiles, I don't want to print


    Thank you, Alenn.

  24. Simon Tite

    Is it possible to do the same with .html files? In my README.md, I put a line like:

    * [Documentation](doc/intro.html)

    It created the link ok, but when you click it, it shows the source of the html. How would you make it display the rendered html as a normal web-page? Is this even possible?

  25. Saad Khattak

    It seems that the relative links do not work with markdown. Or at least it is not working for me. This is my folder structure for the wiki:


    All my images are in imgs folder. I tried ![](imgs/myimg.png) and ![](../imgs/myimg.png) and ![](/imgs/myimg.png). None of those combinations seem to work. Did I misunderstand how the relative image paths work?

  26. Log in to comment