Internal links with IDs instead of relative paths

[JPeer264]

Description / Problem

There is a lot of value in having internal links. Right now there is the possibility to reference another page with [my reference](../../reference/markdown.md). The downside of this is that this link might change in the future as of internal refactors and path changes. So in case markdown.md moves to a complete different directory it will break, as auto updating references

Idea

What if internal linking could be as easy as giving and assigning IDs, where one page has an unique ID inside frontMatter, given manually (e.g. linkId: myLinkingId), and in another document you can use this as path (e.g. [my reference]($myLinkingId)).

I couldn't think of a different or better way of having these references.

Possible issues

• Maybe performance would be a little downer here, as webpack needs to parse all documents first and collects all possible link ids.
• "Broken link detection" might have a harder time in resolving these links

[Josh-Cena]

This has been brought up a few times. I'm strongly in favor of this. However, its potential is severely limited by our current Markdown infrastructure (#6370), and there are also other considerations here.

Since you have thought a little deeper about the possible issues, I'd like to share with you how those are actually non-issues with our current setup. Our Markdown documents are loaded in three steps:

1. Each plugin (docs, blog, ...) hosts its own Markdown loader. This loader does nothing else than transforming Markdown file path links to URL links, because only each plugin itself knows the file path -> URL mapping. The same would happen for your proposed ID -> URL mapping: the core would not care about the plugins' internal data structure.
2. The Markdown files now contain purely URL links. They are passed to a unified MDX loader, where the Markdown is compiled to JSX.
3. The JSX is statically rendered to HTML on server side, during which time each rendering of the <Link> component results in one link being registered. This is how we generate the link graph and facilitate the broken link detection.

As you can see, the broken link detection is a core concern, and it doesn't actually use any plugin data—in its eyes, the Markdown links, <a> tags in React files, file IDs, etc. make no difference—it only sees the <Link> components compiled from the Markdown source. Webpack is also not aware of the documents: the plugins already handled it in-house. We already have the infrastructure of Markdown path resolution.

However, there are two concerns here.

1. It doesn't work in other Markdown renderers other than Docusaurus. This makes the files not portable, and makes content editing a bit harder, until Docusaurus provides its own Markdown editor. It's also why people are generally not in favor of ad-hoc custom Markdown syntax (I know @slorber probably dislikes it more than I do). Now if you ask my API design, it will probably something closer to [my reference](id://myLinkingId), but it still looks... artificial.
2. Many editors offer Markdown refactoring services. For example, today in VS Code, there are actions like renaming headers that works cross-file. It's not very hard to imagine that in the near future, you can use the functionality to batch-update all Markdown links when you move files around, making the problem moot.

However, I clearly see the motivation, and I think it's valuable to have an immutable, file-structure-agnostic identifier for each document that's possibly cross-plugin as well: i.e. you can use the same id:// protocol to link to a blog post from a document page, which is currently not possible even with Markdown paths. We don't necessarily have to invent another API: after we remove the constraint that document IDs always have the file path prepended (#6018), we can simply re-enable the id API in blog posts, so that id can work cross-plugin.

[slorber]

[label](docId://myDocId) is something I'm thinking about, as it does not invent any new syntax which indeed I am not a fan of 😅 .

But this link wuldn't allow to navigate in your IDE, in GitHub, etc, so it's a double-edged sword

And docId changes when the doc is moved to a different folder currently. Do we want to fix this behavior (probably), or invent a brand new "docLinkId"? I'd rather not invent a brand new id for that.

---

Maybe there's a broader abstraction we could build, allowing you to build the linking system of your choice

For example [label](component://@site/src/MyCustomDocLink?id=123) 🤪 not sure how to make this convenient to use in practice though

[Josh-Cena]

Related note: MDN docs use KumaScript macros, so it's something like {{ JSxRef("Object/proto", "Object.prototype.__proto__ accessor") }}. It requires an entire KumaScript infrastructure, though.

[NightMachinery]

UUID links will actually make editor support better IMO; Only highly developed editors have fancy (and often broken) features to refactor all links, etc. But supporting navigation with a UUID is pretty easy and robust. I could even do without having a custom solution, as my editor already supports easily jumping to search results, and I can just search the UUID.

[slorber]

@NightMachinery can you please back your claims with references?

Which editor supports which kind of UUID link?

Can we see demos/videos of it in action?

[NightMachinery]

@NightMachinery can you please back your claims with references?

Which editor supports which kind of UUID link?

Can we see demos/videos of it in action?

I did not say any editors support Markdown UUID links (though emacs does support UUID links in org-mode). I said adding such support is pretty straightforward and easy, as we only need to leverage an existing tool such as grep. I have created such jump-to-search-result for myself before in emacs, and it worked robustly.

Here is a demo of opening a UUID link both by directly searching and using emacs' built-in support:
https://asciinema.org/a/DDmcHeGDWu3DyiYfxCdfy2Fvj

Adding support for UUID links in Markdown to emacs would not be difficult. I think I could do it in a weekend. But crucially, I don't need to do it. I am fine with just jumping to search results.

Here is another demo of a jump-to-search using vim:
https://asciinema.org/a/8cZawtiLv3jx66T3LNbTcf8a0

(The software used in this demo is, unfortunately, extremely coupled to my environment and not easily usable by others. But there are similar tools aplenty.)