Issue #6315 resolved

Relative urls in files only work half the time. (BB-7521)

Nick Zarczynski
created an issue

I have the following project structure:


In my file, I link to the document like so:

[Get started](doc/

When viewing the file in the source tab this link 404's (it points to ../project/doc/

But when I click on the file and view it, the link works (correctly points to ../project/src/31...8e/doc/

There is a (possibly?) subtly different problem for relative links in sub-folders. Given the project structure of:


In the file, if I have a link to style/ as follows:

[Markdown Style Guide](style/

It will break in a similar manner to the above (50% of the time), but with the following urls:

Overview page links to: ../project/src/31...8e/style/

While viewing links to: ../project/src/31...8e/doc/style/

Comments (204)

  1. Brian Nguyen

    Hi Nick,

    Thanks for reporting.

    I've confirmed that the problem with relative links only works if the readme is rendered at a specific commit. If it is rendered generally (like on the overview page), then it will not work.

    I have added the issue to our backlog, and please watch this issue for further updates.

    Cheers, Brian

  2. Matthis Thorade

    Similar problem here: In my file I would like to have (relative!) links to the issue tracker and the downloads#tag-downloads page. Of course the links should work both from the overview page as well as from the source page.

  3. Olivier Scherler

    This is getting ridiculous. What can I do to be notified when (if ever) this is fixed without receiving an e-mail every time someone +1s it? Open a new feature request to allow to watch only the status of issues and not the comments, issue that people will dutifully +1 regularly?

  4. roman.neuhauser

    Olivier Scherler this UI issue should be pretty easy to fix, just put the voting/watching buttons (also) next to the [Comment] button under the comment box. but Atlassian seems to be too busy building their own SharePoint-like abomination by stitching BB together with their other products. they have no time left to fix basic bugs in the constituent parts.

    as for your desire to get rid of comments: you should be able to leverage another bug, issue #8163.

  5. David Seal

    I found that by clicking on "Source", and opening the top-level, then the relative links work.

    With that being said, it would be nice to start from the top-level screen for navigating!

  6. krembo99

    My solution to this is to do One commit with /img folders, and then use the RAW absolute URLs. This will of course work only for a projects with few images and not frequently updated . Otherwise - it is a nightmare...

  7. Andreas Pieber

    It's kind of the same for us. We use the readme viewer as an "internal online wiki architecture documentation" for the software within the repository. Without a fully working relative linking this is kind of a pita...

  8. Russell Steicke

    I searched for how to inline images in, and ended up here. Wow, 13 months this bug has been open.

    Absolute URLs in source is not just inconvenient, it's wrong.

    For me, this has reduced the utility of bitbucket to private repos only. As soon as it's public, and I may want to have a decent looking README page, it's off to github.

  9. Lars Janssen


    We're actually paying for this service. Don't expect everything fixed straight away but with 170+ votes and all these comments, how many hundreds or thousands of people are affected but just worked around it or moved on?

  10. Anonymous

    For gods sake, please use the voting feature instead of your "+1"-posts. It's very annoying to get a notification e-mail for every one of this. Thank you.

  11. Rick Schmitty

    Viktor Steinwand and Martin Kramer do you guys even read? Enough already with the +1 responses. No one is even assigned to this ticket. All you are doing is annoying the crap out of everyone who already wants this feature.

    If you want to make a difference VOTE for the issue using the link next to total votes

  12. Andy Mayer

    Rick Schmitty I for one like the +1's and my email program preferences makes them not a problem nor even a minor nuisance. They remind me that I still want to see this issue resolved, and temp me to do another +1 myself. Can you not just un-watch the issue if you do not care for the emails?


  13. Vitaly Pavlenko

    Can you not just un-watch the issue if you do not care for the emails?

    Of course, no. If there is a day when the issue gets assigned or even implemented, how could I know about that?

  14. Ember Quill

    Over a year and still not fixed? Kind of annoying, especially since it only seems to affect the overview, which is the very first page anyone looking at the project will see.

  15. Bogdan Yurov

    Seems like bitbucket staff completely ignore most of issues on this bugtracker. Even trivial bugs are not fixed.

    The only reason we still use it is price.

  16. Vitaly Pavlenko

    Guys, I really like this awesome chat of people who can extract the quality of Bibucket's customer care from this evident example. That's the best discussion I've subscribed to ever.

  17. Bogdan Yurov

    Vitaly Pavlenko You see, voting is not effective. Maybe at some moment one of Atlassian managers would see this "chat" of angry customers and notice that they should just fix issues in time rather than issuing tons of commercials to get positive feedback and new happy customers.

    ...also you created another wave of spam.

  18. Olivier Scherler

    We have almost 16 months of evidence that the four techniques (+1, voting, polite reminders and snarky comments) are all exaclty equally effective.

    This is not a complain about the people doing those.

  19. David Vins

    You have to love the fact at one point they saw fit to assign the 'duplicate' to someone, who then closed it out as a duplicate, yet no one has been assigned to this one.

  20. GS User

    Added my vote. We're in the same situation as several other posters of wanting to create documentation for our business partner, but the lack of relative links is a huge limitation... I'm questioning whether this is even a viable way to proceed because of it.

  21. Ed Kohlwey

    Or you could always just switch to Github, where they have basic functionality working.

    All of Atlassian's products actually integrate very well with Github, so it would just be that one migration.

  22. Michael Diamond

    While it's not ideal, I was able to create a reliable link on my custom domain by including the repository name in the URL:


    This link works both from /myrepo and /myrepo/src/tip/

  23. Matt Walker

    I'd also love to see relative links in markdown supported. I've just added a screenshot in a readme and found that once pushed it's shown as a broken image when previewed on I frequently use relative links in markdown files for images and navigation on GitHub (and locally via the Chrome Markdown Reader plugin), was really surprised to see it broken here.

  24. Ben Peachey

    A JS solution for this would be pretty much trival to implement

    Maybe the time has come to just write a [your favorite browser here] plugin or favelet to introduce this (and other) missing behaviour to BB.

    There goes another 20 minutes of my time cry

  25. Jonathan Rehm

    Since Bitbucket is taking their sweet time fixing this and I'm tired of seeing broken images in my repo's, I took Ben Peachey's advice and made a JS solution. Currently I'm using Control Freak to run the JS when I navigate to Bitbucket.

    I hate that this type of thing is necessary. Come on Atlassian.

    Note: depends on jQuery because I don't feel like re-inventing the wheel with looping over DOM queries and vanilla JS event binding.

  26. Thomas Venturini

    I think they won't fix this issue. But they have the wiki functionality for this. Also I think that we should use the files just for direcotry overviews and link to the wiki pages if there is more information to give.

    This way it is working quite nice for me. And although the wiki is build of markdown files, and edited as a repository, the links in there work just fine ;)

  27. Ethan Winn

    I hate to pile on here, but it's worth calling out that many high profile projects on GitHub use this feature to very good effect. Examples include HTML5 Boilerplate and Puppet.

    This isn't an edge case, it's now a standard pattern. For those of us recommending Bitbucket as a devops tool for our clients, not being able to follow the pattern is challenging.

  28. Lea Hayes

    When attempting to embed images using relative paths it seems that the images break since Bitbucket is returning a page rather than the raw image.

    What if a query parameter was introduced that allowed us to specify a raw link more easily?

    ![My Image](img/RelativeImage.png?raw=1)
  29. Jasper Valero

    +1 and voted...

    Add me to the list of people who think this is a bit ridic that it hasn't been fixed considering it was opened back in the beginning of 2013. John Garcia, Jon Mooring and everyone else who have marked other tickets as duplicates, you obviously know this ticket exists. What's the logic behind not even responding with an update?

  30. wkretzsch

    Sat in on a talk to a packed room (30 bioinformaticians) explaining how to use knitr with .md files to produce nice reports with integrated graphics together with git versioning. git-hub was introduced as the website for rendering the .md files. I asked if anyone used bitbucket (3 hands) and I had to point out that this would not work with bitbucket because of this bug.

  31. John Jensen

    Being that this issue has been around since February of last year, what are the odds of this getting fixed any time soon ? This is a really annoying flaw, and one that is deterring migration from Github as indicated by other users above.

  32. Ike DeLorenzo

    Certainly you would expect relative URLs in a readme to work. And the workaround of using fully qualified URLs isn't very satisfying. This bug's longevity has been related to our continued support for some small-minority markup languages like Creole.

    Our focus here is to fix this bug and move forward with supporting relative URLs in the two languages that make of the vast majority of Bitbucket readmes: reStructuredText and Markdown. We are working to make this happen in the coming quarters.

    -- Ike DeLorenzo, PM, Bitbucket Team

  33. Lucas Mendes de Freitas

    Ike DeLorenzo thank you for the feedback, relative urls in markdown would be a good improvement to the bitbucket platform, because we're using bitbucket as our project management and VCS in company and this bug is causing some problems with our repositories and this issue are opening since 2013 without feedbacks, anyway, thanks a lot.

  34. anatoly techtonik

    Ike DeLorenzo, drop Creole - it is dead, because comparing syntaxes is not a usability study, and if they tried to do usability study, they'd know that pipe | for links should not be used, because it is absent from Russian keyboard layouts. Also, they tried to use double [ ], probably to avoid errors when copy-pasting from text files (or maybe just biased towards MoinMoin syntax they use), but using double [ ] hurts readability, and using [ ] for biographic references are rare in code repositories.

    So, if Markdown usability suffers because of Creole support, drop Creole and add link to markup converter. It will make 453 people happy.

  35. Edward Grech

    I am using the following dirty hack to make the image be shown both offline and online:


    When viewing locally, the first is activated and the second is a dead link; and vice versa when viewing on Bitbucket. It’s not very nice, but at least it makes the documentation readable everywhere.

    Of course this will only work if you know REV, so it can’t always work. But if REV is a branch name, at least it will “work” when viewing the documentation at the head of that branch.

    But come on guys, it must be such a simple fix… when parsing the links in a Markdown file interpret them as raw! We shouldn’t be resorting to these silly hacks.


  36. Adrian Schnyder

    My temporary solution is to put the graphics to the internal wicki and link them to the readme. This approach works locally and on Bitbucket also.

  37. Adrian Wadey

    My Workaround

    Don't use the bitbucket image tool to add images on-line, rather:
    Download the wiki repo
    Add images to the repo (I use an "images" folder)
    Link to the image like this:

    ![Sequence Panel](./images/SequenceSubPanelsm.png)

    Push the repo back to bitbucket
    This works for me and I can convert the markdown to other formats using pandoc (pdf, word, ebook) and the images show up in them and in the wiki

    There are a couple of caveats

    No spaces in the path or filename I work in windows and I had it working on my local machine but the images wouldn't show when pushed and viewed in the wiki
    The case of the path/filename in the link must match exactly Again, in windows case is ignored, but on the wiki it isn't

  38. Mogens Heller Grabe

    This functionality is provided by GitHub. It is disappointing that this has not been resolved as it significantly impairs the ability to document repositories hosted in BitBucket.


  39. John Schank

    My company just recently started paying for bitbucket. The fact that this issue has been open for so long, and has been ignored, leads me to believe that I will not find good support here at bitbucket.

  40. Adrian Rowbotham

    Please ensure you vote for this issue – it's not top of the issues list when sorted by number of votes.

    Adding an angry comment (however valid) does not help raise its profile as much as a vote.

    (Edit: that said, there is one that's been open since 2010! so maybe @john_schank is right)

  41. Ben Peachey

    Heath Morrison Not the highest... The following bugs all have a higher vote and are older than this one:

    • Feature Request: Contributor Statistics (BB-4787) - 2012-07-05
    • Create a way to group repositories/projects by tags, folders or labels (BB-1086) - 2010-12-06
    • Ability to search source code? (BB-39) - 2011-07-21
    • Support two-factor authentication (BB-7016) - 2012-12-26
    • Allow admins to specify read/write/admin permissions for wiki and issue tracker separate from repository (BB-1166) - 2011-01-31

    Not to say this should give you more convidance that voting actually achieves anything stuck out tongue winking eye

  42. John Schank

    Yep, I voted. So when can I expect this to be solved? BTW, it seems like bitbucket wikis can do exactly this: they are markdown, they are repos, they have images. Or is that wrong? Are wikis on bitbucket as worthless as markdown in readmes?

  43. John Schank

    I don't mean to sound so angry, but I am trying to lead a company away from CVS (yes CVS) into a modern age of git DVCS repos. So when my project readme file can no longer show clarifying images. Then it diminishes confidence in the entire effort. I might understand better if no other service could do this. (BTW Gitlab can also do this) Or if I could show that bitbucket is responsive to its community. But research into this problem has led me here and to the to the other, similar thread, which has been marked as a dupe. And what I'm seeing is not filling me with confidence.

  44. Adrian Rowbotham

    @john_schank My comment wasn't targeted at you individually, I'm just getting a lot of comments on this and wondering if everyone is voting too. I agree - apparent lack of caring is most discouraging.

    Ironically everyone subscribed is now getting a deluge of comments because of my comment about comments.

  45. pukoren

    This is ok, I receive a lot of mails about this issue and each time it makes me smile thinking something so basic is still not solved. At least this post is useful for something since bitbucket don't give a *

  46. Bill Perry

    Guys, given that this issue as existed for so long, and no one is even assigned to it, I'd say it is pretty safe to say that it is not going to get fixed because it is not perceived to be an issue of any importance. My suggestion at this point in time is to give up on it ever being fixed. If you need the functionality then vote with your feet and walk on over to GitHub where this as well as 2 factor authentication works.

  47. Ember Quill

    Bill Perry Yeah, I gave up on BitBucket last year, though it was primarily because of #589. That issue was five years old (now almost six) and the first time a staff member actually commented on it was seven months ago (after I had already given up and switched to GitLab), just to tell us that nobody was currently working it.

    Of course both that issue and this one were addressed in Stash ages ago.

  48. Marcin Ziemian

    This is absolutely insane, it's been two years, TWO YEARS, and this still hasn't been fixed? Using absolute links is flat out not viable which is why both this issue and Issue #6589 are so popular. I bet the bitbucket team sits during their meetings thinking up of ways to encourage people to use bitbucket instead of github, coming up with attempts costing thousands in developer time or advertisements. But no, let's leave something as basic as relative images untouched, for two years.

  49. Tom Roche

    Based on this comment from Ike DeLorenzo, I suspect this and another bug may be related. I'll try to create a Markdown-specific version of my reST-relative-link test project, which shows similar results:

    1. from README files, viewed as overview pages:
      • links to {downloads, issues, wikipages} work iff the project name is the first segment in the path (i.e., Bitbucket style)
      • "standard" (i.e., Unix-style) relative link paths to reST wikipages work with or without file extensions (.rst)
    2. from other non-wiki reST files, viewed in source context:
      • standard relative links to other non-wiki reST files work, but only with file extensions
      • relative links to (reST) wikipages always fail
      • Bitbucket-style relative links always fail
    3. from (reST) wikipages:
      • standard relative links to {downloads, issues, other wikipages} work
      • Bitbucket-style relative links always fail
  50. Tom Roche

    A few questions to and comments for folks in this thread saying or thinking, "I'm going to Gitlab":

    Main question is, how's that working out? I exported my Bitbucket reST-relative-link test project to a Gitlab project, and I'm not seeing any improvement--in fact I'm seeing degradation. The contents of the two projects are identical: you can (e.g.) compare their READMEs here and here, and their wiki homepages here and here.

    Yes, I'm aware that I'm talking about reStructuredText and not Markdown, but my reST issue was marked as duplicate of this, so I'm posting here. My empirical subquestion is, does Gitlab Flavored Markdown provide a better intraproject/relative linking experience than does Bitbucket Markdown?

    Some comments for folks considering moving projects from Bitbucket to Gitlab:

    1. Bitbucket uses project_name/wiki/, Gitlab uses project_name/wikis/
    2. Perhaps due to item#=1, automated import of a Bitbucket project from Gitlab fails to import the project's wiki. (GL import did copy project issues for me, but I noted a GL issue someone else filed on BB->GL importation of project issues.) However manual git push from the local root dir of my wiki (.../rst_link_test/wiki/) to the appropriate GL wiki URI WFM.
    3. AFAICS, Gitlab does not support project downloads (e.g., out-of-repo binary assets), while BB does. This may be important to you if, e.g., you do scientific computing and want to capture but not VC images/figures generated by your code. (That's why I moved many projects from Github to BB originally.)
    4. Tables of contents in Gitlab *.rst appear to be completely broken currently. I dunno how this is working in GL *.md: ping me if you know.

    I can definitely see how Gitlab could be advantageous for folks seeking to run their own repo infrastructures. But I'm not seeing any win for BB->GL WRT this particular issue, or for web-repo users generally--am I missing something?

  51. John Schank

    Hi Tom, My project used to be in gitlab, and there I could reference images by creating an images directory in the repo, and then in the readme I could like to “images/some.jpg” and it worked fine. The important thing here, is that the links resolved even locally, so when I would render my document locally the images would also resolve. When I moved to bitbucket, however, not only did relative linking stop working. BUT the technique that does work, only works on bitbucket, if I open/render the document locally, I get broken links.


  52. Tom Roche

    @John Schank: 'in gitlab [I] could reference images by creating an images directory in the repo, and then in the readme I could [link] to "images/some.jpg" and it worked fine.'

    Empirically (see for yourself!) this fails with reST in Gitlab:

    1. GL image is here.
    2. In GL README, scroll to section='an image'. You can try browsing directly to that section, but GL internal links are not working for me (in latest Firefox on Debian, FWIW). Note that none of the images resolve, including images/Jen_Sorensen_PandP-poster-ForWeb.png.
    3. You can also view the README page text here, just to note all the ways I'm trying to exercise link-path syntax.

    Then compare to reST in BB:

    1. BB has image
    2. Scroll to section='an image' in BB README. Not much better, but at least BB will show rst_link_test/downloads/Jen_Sorensen_PandP-poster-ForWeb.png (which I'm calling "Bitbucket style" link-path syntax). Why won't BB display rst_link_test/images/Jen_Sorensen_PandP-poster-ForWeb.png? or images/Jen_Sorensen_PandP-poster-ForWeb.png? I have no clue.
    3. You can also view the BB README page text here, just to note that it's identical to the GL README text.

    Has anyone got an equivalent Markdown link-test project? That could be deployed on both BB and GL (etc) for testing link-path support?

  53. Tom Roche

    Note also that (as of 27 Apr 2015)

    • in this README.rst/overview--i.e., in my reST link-test project--true relative links to the wiki (e.g., ./wiki/Home) now work.
    • in the, 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.

    For (much) more (than you ever wanted to know :-) about the current state of this issue, see this comment.

  54. John Schank

    It is important to note that a pseudo-relative link, such as you describe, will NOT work on a local filesystem. What I mean is that I want to see my images rendered even if I open the in a markdown editor on my local machine, as well as have them rendered when hosted on bitbucket. GitLab, and I believe GitHub can both do this.

  55. 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 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.

  56. Tom Roche

    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.

  57. domainfun

    Kaleb Elwert: Instead of just saying an issue was closed as resolved, it would be helpful to state a link to Atlassian Documentation which outlines the new behaviour. I just found that a repo's links in the to the same repo's issues and wiki were broken (in a paid BB account with my employer). Nothing in the examples provided by Tom Roche seemed to help ( After searching for official Atlassian documentation in vain (perhaps I'm just blind), I worked out that changing (issues) to (../../issues), and (wiki) to (../../wiki) seems to work reliably, i.e. for all four possible URLs which show a repo's overview page on BB:

    Hope this helps someone (I wasted a whole hour of my time).

    PS: It's not clean HTML though, e.g. View Source shows <a href="/account/repo/src/random-string/../../issues">Issue Tracker</a>, and also & characters aren't HTML-encoded, such as in <a href="/account/repo/src/random-string/../../issues?status=new&status=open">work in progress</a> the ampersand should be &amp;. The latter is presumably a BB issue in itself, as standard Markdown implementations do this properly.

  58. Log in to comment