summary

In project=rst_link_test I observe that relative links in reST files work only as follows:

1. from README files, viewed as overview pages:

1. • 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)
   • all links to in-repo images fail (except presumably standard absolute URIs, not tested here)
2. from other non-wiki reST files, viewed in source context:

1. • standard relative links to other non-wiki reST files work, but only with file extensions
   • all links to in-repo images fail (with caveat above)
   • relative links to (reST) wikipages always fail
   • Bitbucket-style relative links always fail
2. from (reST) wikipages:

1. • standard relative links to {downloads, issues, other wikipages}

     work

   • standard relative links to project resources (i.e., files in project repo, not wiki repo) fail
   • Bitbucket-style relative links always fail

details

[Note that this issue is probably related to BB-7521 per this comment from Ike DeLorenzo.]

While writing reST files (mostly {{README}}s and wikipages) for several projects, I have noticed much weirdness with relative links. Eventually I decided to write a small but reasonably complex project=rst_link_test to exercise different link syntaxes in reST files in different contexts. I obtained the results summarized above: feel free to have a look at the project yourselves.

Note that, IMHO, consistent/robust support for standard relative link syntax is important, to maximize

• utility with documentation processors
• portability to/from other doc stores