Is there a way to use cross references instead of links?

[stoobie]

AsciiDoc uses xref:target.adoc[Link Text] for links to pages within the same project. These are great because they’re path-agnostic, so I can put them in an included file and no matter where in the file tree the snippet is inserted, the xref resolves correct. Also, I don't need to include Link Text because the topic title appears if you leave it empty. I’m trying to find a MkDocs Material equivalent — something more robust than Link that can catch broken links at build time and avoid brittle relative paths.

Does anything like this exist in the MkDocs/MkDocs Material ecosystem? If not, how are large projects managing internal linking and avoiding breakage?

[kamilkrzyskow]

Hi @stoobie,
there is no built-in way to do that, but there were multiple attempts in the community to help with that and partially solve the issue.

One could be the plugin which will generate the relative paths for you, assuming the Markdown file name is unique. This approach is sort of hands-off, which I think is what you want.
https://github.com/zachhannum/mkdocs-autolinks-plugin

Note

EDIT: As found by Steve in the comment below, there is also another plugin, which is more recent and up-to-date, and therefore it looks like a best place to start with.
https://mkdocstrings.github.io/autorefs/

Another approach would be to use some sort of semi-automatic redirect creation for pages that have been moved:

• Is there a way to permanently link to a page even if the page changes? #3758
  The approach adds some overhead, and isn't perfect since the redirects would be static pages with a redirect link, so no a true 404/403 HTTP status code.

I once took this approach and adjusted it to work with git history, so it would detect Rename / Move actions in git and configure the redirects. However, this too wasn't perfect as it required to take care to properly commit changes as Rename / Move type, so not completely hands-off, also the same cons apply as above apart of being more automatic:
https://github.com/Gothic-Modding-Community/gmc/blob/dev/overrides/.hooks/git_redirects.py

MkDocs process pages sequentially, one after the other, so any solution where you store references* to pages and allow to cross-link them in Markdown would require some custom solution. Maybe there is already one, but I missed it in the catalog.

* Other than their filename (used in the plugin above), like some kind of short handle / ID

Ref:
https://github.com/mkdocs/catalog

[stoobie]

@kamilkrzyskow What about https://mkdocstrings.github.io/autorefs/?

[kamilkrzyskow]

@stoobie
I haven't used autorefs but it was recently maintained by the mkdocstrings team and they're MkDocs professionals.
So I would have to agree that this looks like the best place to start. Thanks for sharing, I'll update my answer 😄