Header links working in Jupyter Notebook/Lab but not on a site built with MyST-NB

[maximlt]

Hi all!

TL;TR

We've found that links to headers that work when working from within Jupyter Notebook/Lab no longer work when on a page built from the same notebook with MyST-NB. We're not sure how to deal with that so that these links work in both context.

Details

So let's say you have this bit of Markdown in a notebook. Note that the link is #My-Title, it's cased as the header it's pointing too. This works, from your notebook you can click on the link and gets redirected to the linked header.

[A description](#My-Title)

# My Title

However, the link as defined above does not work when that notebook is built with MyST-NB. Apparently MyST-Parser auto-generates header anchors and the docs say:

The anchor “slugs” created aim to follow the GitHub implementation:

• lower-case text
• remove punctuation
• replace spaces with -
• enforce uniqueness via suffix enumeration -1

So in the simple case above, the difference seems to be in how the slug is cased. If the link would be written as [A description](#my-title), so all lower-cased, then that link would work on the website. But it would no longer work in Jupyter Notebook/Lab 🙃

Is there any way we could write these links so that they work in both context?

MyST-Parser docs suggest that to change the slug generation function, set myst_heading_slug_func in your conf.py to a function that accepts a string and returns a string, so I assume we could overwrite that function to at least not lower-case the slugs. I'd prefer a more lightweight solution though.

[maximlt]

BTW it might well be a Jupyter Notebook/Lab issue? I haven't managed to find the reference for how these local Markdown links should be defined in a notebook.

[rowanc1]

You might want to checkout the jupyterlab-myst extension, which should use the same enumeration strategy as myst-nb (if it doesn't we would treat that as a bug). The snippet you posted does work, and the extension also allows for admonition rendering and many other directives like tabs, grids, cards and cross-references. We released a major version yesterday:
https://github.com/executablebooks/jupyterlab-myst

[maximlt]

Thanks for your answer! While jupyterlab-myst is an extension I will use for sure, I can't really expect all consumers of the notebooks we make downloadable to have it installed. So until it's a default extension of Jupyter Lab/Notebook, that situation is a little unfortunate :)