reStructuredText relative links work in some contexts, not others

Issue #11238 duplicate
Tom Roche created an issue

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:
    • 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:
    • 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
  3. from (reST) wikipages:
    • 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 READMEs 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

Comments (3)

  1. Log in to comment