Automatically treat relative links as cross-references

[asmeurer]

I don't know if this is within scope or not. It would be nice if relative links like

[link](page.html)

or

[link](page.html#header)

were automatically translated to cross-references, and especially if it didn't require adding a (header)= to the header if the slug is already named that.

The former does not work at all (it produces an error). The latter does work, but I believe it is just treating it like an external link, meaning if there is a spelling mistake in the page.html#header part it won't catch it.

A potential issue might be that Myst documents could be included alongside other documents, so you can't guarantee that a page that you can't find a reference to isn't something that will be there anyway. I don't know if that is the case.

[chrisjsewell]

Have you tried just [link](page). The doc-role doesn't accept an extension (sphinx intrinsically doesn;t store the extension of pages). there is an issue in one of the repos about allowing this in the myst syntax though

[chrisjsewell]

In general with sphinx (rST or MyST) I would always advise using specific targets over document/header names, since they are obviously lot more resilient to changes/refactoring of the documentation

[asmeurer]

Yes [link](page) works (#148 not withstanding). [link](header) works as well, but only after I add (header)=. The way I suggested is the way you have to write links in recommonmark, and it's also the way I would naturally write links in Markdown.

[chrisjsewell]

Did you mean to but back-ticks around those links?

[chrisjsewell]

Anyway these issues probably don't have a quick fix and I'm signing off for the evening, so will get back to you on these at a later time

[choldgraf]

re: linking to headers without explicitly defining labels, doesn't recommonmark just use this sphinx extension? https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html (which auto-adds labels for all section labels). If so, you could just activate that extension as well if you don't want to manually add labels.

[asmeurer]

Oh I didn't know about that. I'll give it a try. If you don't want to make this a default that's fine with me. I'll leave you to discuss that. Either way though maybe Myst could document that it's an option in the cross-reference docs.

[pradyunsg]

A borderline drive-by comment that it'd be nice to have the answer to "how do I link to a header in a different page in MyST" documented somewhere. :)

[chrisjsewell]

https://myst-parser.readthedocs.io/en/latest/using/howto.html#automatically-create-targets-for-section-headers?

[chrisjsewell]

In fact this issue can probably now be closed, given: https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html#auto-generated-header-anchors

[pradyunsg]

Yeap!