Add support for cross-referencing

[sid-kap]

It would be nice to have something like http://sphinx-doc.org/markup/inline.html

In rST you can do

:doc:`A link <relative/path/to/page>`

rST supports other directives as well, but I think referencing documents is the most important.

Github Wiki supports something like this with the Mediawiki syntax: (see https://help.github.com/articles/adding-links-to-wikis/)

[[A link|Page location]]

I'm not a huge fan of this syntax. I think the syntax should be more similar to the ordinary markdown link syntax. Maybe something like:

[A link](/path/to/page)

(here we assume that any link beginning with / is a cross-reference to another page in the Sphinx directory, relative to the source directory. In sphinx, a link starting with / is considered a path from the root.)

Does something like this seem like a good idea? In general, adding syntax rules to Markdown is frowned upon, but this one might be worth it. I can't see how you could make an entire readthedocs site in markdown with using relative references.

[ericholscher]

I'd like to implement this as generic syntax, as discussed here:
http://talk.commonmark.org/t/generic-directives-plugins-syntax/444

We had a basic implementation of it on a previous branch, but there are
some design decisions that I'll try and write up when I have a bit more
time.

On Wed, Aug 12, 2015 at 3:25 PM, Sidharth Kapur notifications@github.com
wrote:

It would be nice to have something like
http://sphinx-doc.org/markup/inline.html

In rST you can do

:doc:A link <relative/path/to/page>

rST supports other directives as well, but I think referencing documents
is the most important.

Github Wiki supports something like this with the Mediawiki syntax: (see
https://help.github.com/articles/adding-links-to-wikis/)

[[A link|Page location]]

I'm not a huge fan of this syntax. I think the syntax should be more
similar to the ordinary markdown link syntax. Maybe something like:

A link

(here we assume that any link beginning with / is a relative link within
the sphinx source).

Does something like this seem like a good idea? In general, adding syntax
rules to Markdown is frowned upon, but this one might be worth it. I can't
see how you could make an entire readthedocs site in markdown with using
relative references.

—
Reply to this email directly or view it on GitHub
#8.

Eric Holscher
Maker of the internet residing in Portland, Oregon
http://ericholscher.com

[tqchen]

This is supported already by auto structify component, see http://recommonmark.readthedocs.org/en/latest/auto_structify.html#auto-doc-ref

[pfultz2]

In the parser, if we add the reference nodes as sphinx.addnodes.pending_xref instead of docutils.nodes.reference then sphinx can resolve the links instead of needing things like url_resolver. Plus, it could be added with the any role so it could cross reference domain elements as well.

[pfultz2]

Ok, so I updated the parser to use pending_xref for references in this branch here. However, it requires sphinx to be updated with this pull request here.

For links that use http:// or https://, it still uses docutils.nodes.reference, since they are external but other links are added using pending_xref with the type set to any. This is really nice, and allows me to cross reference more than just documents. Plus, I get warnings when sphinx can't find a reference, and I can use the standard missing-reference event from sphinx to resolve references.

Once the pull request is merged into sphinx, I can send a pull request for this as well(although sphinx has yet to respond to my pull request).

[mizzao]

I just converted a Jekyll site written with Markdown to Sphinx and kept files in .md to ease the transition (https://github.com/TurkServer/docs). Took me a while to figure this out, but I just built on RTD and had to

1. Enable AutoStructify and configure url_resolver with the correct repo path
2. Force a newer version of as in make html works locally, however, RTD fails to build -- any ideas? #29 (comment)

Hope that helps anyone else who stumbles upon here, and is trying to get their Markdown cross-referencing to work.

[dafeder]

What I'm having trouble doing is linking from an RST file to a markdown file. Anyone able to do this?

[lorengordon]

AutoStructify doesn't seem able to link to an anchor in the target page.

Works:

[Some Page](doc.md)

Doesn't work:

[Some Header](doc.md#some-header)

If that is supposed to work, anyone know the magic incantation (syntax)?

[pfultz2]

Its probably better to have sphinx resolve the links by having recommonmark generate a pending_xref, instead of reimplementing this logic twice. Doing it this way, you can link to 'Some Header' as [Some Header](Some Header), or define your own anchor names using inline RST.

[lorengordon]

@pfultz2 looks like your pull request was merged into sphinx and released in v1.5. Perhaps open a pull request to merge your pending-xref branch into recommonmark?

[pfultz2]

Got it, I sent PR #61 to update this.

[redihokuto]

Thanks Mizzao for your working example.
I have downloaded the docs-master and built it locally.
Not all links are working.
In the intro.md the reference to "quick start" is ok, but the others 2 that embed a folder are not working.
During building, I've got

D:\prj\python\sphinx\docs-master\source\intro.md:16: WARNING: unknown document: /design\assigning
D:\prj\python\sphinx\docs-master\source\intro.md:17: WARNING: unknown document: /arch\admin-console
D:\prj\python\sphinx\docs-master\source\intro.md:19: WARNING: unknown document: /design\mirror
D:\prj\python\sphinx\docs-master\source\intro.md:53: WARNING: unknown document: /examples\tutorial
D:\prj\python\sphinx\docs-master\source\intro.md:53: WARNING: unknown document: /design\design

No links are produced in the HTML output

My expectation is to write [quick start](quick-start) without the .md
I have a similar issue with a test project of mine, which is structured as

earth.md
facts/earth_facts.md

I'm not able to obtain a working link to facts/earth_facts.
The text I would like to write in earth.md is [Earth Facts](facts/earth_facts)
The generated link is instead file:///D:/prj/python/sphinx/khaba/build/html/earth/earth/facts/earth_facts
Where earth gets duplicated in the path and the link is missing the .html

By the way,

 'url_resolver': lambda url: url,

In the function auto_doc_ref inside transform.py, uri = earth/facts/earth_facts and docpath is None.

Any idea?

[pfultz2]

@redihokuto Try installing my fork instead with pip install git+https://github.com/pfultz2/recommonmark@pending-xref, and do not enable auto structify. It should work how you expect, as all links are treated as the :any: role by default unless they are urls.

[redihokuto]

@pfultz2 Thanks a ton! Exactly what I wanted (be treated as :any:). Just tested and works great.

[redihokuto]

@pfultz2
I found the following
[](facts/earth_facts)
causes and Exception
It seems a valid syntax in commonmark (a zero or more...).
My expectation is to have the page title as link text (as your fork is doing), while if I specify a link text, [xyz](facts/earth_facts), the link text should be xyz.
We have the equivalence

[](facts/earth_facts) --> :any:`facts/earth_facts`
[xyz](facts/earth_facts) --> :any:`xyz<facts/earth_facts>`

The same for refrence links: [][bar] and [foo][bar]
What do you think?

[pfultz2]

What do you think?

That makes sense. I'll try to update it.

[redihokuto]

@pfultz2
Today I checked here the result of [](/url). It gets translated into <p><a href="/uri"></a></p>, no text displayed if rendered. I don't want to break any standard, but I think it's more useful to let the system pick up the title of the page and use it as link text, as your fork is doing. It would be always possible to add a configuration item to stick with standard behaviour if one is interested in (sincerely I don't see any advantage on it).

[honzajavorek]

Hi, I couldn't make the referencing work correctly.

• First, according to this issue it seems to be a work in progress,
• second, the links were not correct with either settings I tried,
• third, the syntax commonly used to link to particular sections [link text](file.md#section) did not work.

I made an extension to Sphinx, which collects information about local links and then just reconstructs the links according to what I need. The code is Open Source. It might be naïve, but it works for me. As a bonus, if the local reference (including anchors) doesn't exist, my extension breaks the build.

Ideally, my work wouldn't be necessary at all - I'd love to have this somehow incorporated in recommonmark. Would the recommonmark project be interested in something like this? I'm happy to contribute, to rewrite it into sth more robust, but I need to know it would be desired and I need guidance. Also, if anyone wants to use that code themselves or get inspired by it, here you are.

[ghost]

@ maintainers: may I ask what the state is regarding the [link text](file.md#section) link style?

Is there some decision on whether this will be fixed/implemented, or is there another recommended style that works? (that would be odd though, pretty sure that's the most common one) Or is the official recommendation to use @honzajavorek 's extension?

It would be neat to know if this will be made to work because for documents also written to work on GitHub, this is the expected way to link to sub sections inside documents

[gibfahn]

@ maintainers: may I ask what the state is regarding the link text link style?

Not a maintainer, but I found that for linking to sections within files the easiest way to do it is to use autosectionlabel and the path/to/file:Section Name syntax (added docs for it in https://github.com/readthedocs/recommonmark/blob/master/README.md#links).

For linking to files themselves you can use the /path/to/file syntax, but I find that directly linking to the title is nicer, means all your links can follow the same format, so with a page:

path/to/file.md:

# Page Title

## Section Heading in Page

To link to the page you'd do [file](<path/to/file:Page Title>), and to link to the heading you'd do [heading](<path/to/file:Section Heading in Page>). The nice thing is that this works for rst and for md docs (it's all handled by Sphinx).

There is one issue with this right now, see #165