Wikilinks `[[ ]]` syntax for cross-references

[choldgraf]

Describe the enhancement you'd like

In the wiki world, it is common to use wikilinks (like [[mylink]]) for references within and between pages. This is quite similar semantically to references/cross-references in Sphinx, and we currently use Markdown syntax to map onto the any role accordingly (so effectively becomes {any}`my-ref`

This issue proposes that we create a markdown-it-py extension for wikilinks, and map its rendering onto the {any} role within Sphinx. Basically, we'd make it behave like:

• [[my-ref]] -> [](my-ref)
• [[my-ref|Some text]] -> [Some text](my-ref)

Does this solve a specific problem?

This could be beneficial from people that are familiar with using wiki-style syntax for knowledge-bases. The "wiki world" is a pretty big global community, and is similar in many ways to the open source documentation ecosystem, so there might be some nice parallels here. In addition, I often find myself using "empty markdown link" syntax for the {any} ref like [](my-ref), and if this is a common use-case, then it might be easier to read/less-verbose if we used wikilink syntax instead [[my-ref]].

Additional context

• wikilinks description in Wikipedia
• wikilinks description in mediawiki
• wikilinks in another markdown parser
• markdown-it extension for wikilinks

[choldgraf]

Note that I don't think this is a "must have" feature, but I wanted to write down the idea in case others thought it was of interest as well!

[felixchenier]

I think this would be an excellent idea. I am starting to use Obsidian to manage my documentation website that uses myst-nb, and one of Obsidian's great strengths is its ability to update all internal references (all in wikilink form) when a file is renamed. Therefore, using wikilinks would allow my website to be more robust and would encourage me to do more internal linking without fearing to break those links in the future.

[jpoa]

Greetings, I also think this would be an excellent idea. I came here after trying to solve this problem, and the only two points (that I could find) discussing this was this issue and this: https://github.com/MacqGit/sphinx-obsidian

I would prefer this to be part of MyST directly.

[chrisjsewell]

In light of jupyter-book/myst-enhancement-proposals#10, I think this can be closed, or at least it should be moved to a discussion in the spec

[matterhorn103]

In light of jupyter-book/myst-enhancement-proposals#10, I think this can be closed, or at least it should be moved to a discussion in the spec

The way of doing cross-references that that introduced is very nice, but it is somewhat MyST-specific. Is there any chance of an optional extension that permits Wikilinks and converts them internally to be equivalent to the MyST version?

It would be great for Obsidian intercompatibility for example.