Best practice for internal cross-references that work in both JupyterLab and JupyterBook?

[fmaussion]

Hi all,

I’m authoring a notebook that I want to be readable and navigable both in JupyterLab and when rendered as a JupyterBook. In particular, I want to include internal links like:

[⁵](#References)

This works fine in JupyterLab (where #References links to the ## References header), but it doesn’t work in JupyterBook, likely because of how anchors are handled.

Is there a recommended way to define anchors or cross-references that are:
• Rendered cleanly and function in both environments?
• Ideally compatible with MyST Markdown?
• Not too disruptive to the notebook reading experience in JupyterLab?

I’ve seen :::{#references} and <a id="references">, but they behave slightly differently across environments. I’d love to hear what the best practice is for ensuring internal links work across both formats.

Thanks in advance!

[agoose77]

JupyterLab's MyST renderer uses the same tools that Jupyter Book 2 uses. Jupyter Book 1 uses the old Sphinx stack, whilst Jupyter Book 2 uses MyST-MD as the underlying engine.

You should look to add explicit anchors to your headings, which will allow you to control the targets. For example:

(a-target)=
## Heading with a target

See [](#a-target) for more details!

[fmaussion]

Thanks for the quick reply @agoose77 !

Are you sure this works in JupyterLab? The link doesn't work in JLab 4.3.5

Also, (a-target)= renders poorly in the notebook, which brings me back to my usual rant ;-) (https://github.com/orgs/executablebooks/discussions/1262).

"rant" here is not meant to criticize - I'm a jupyter power user and so thankful to the ecosystem maintainers like you!

[fmaussion]

FWIW I now dedided to to following:

I added an anchor to the heading with the same name as the header, e.g.:

(References)=
## References  

This way, JLab is happy with:

Have a look at [the refs](#References)

And so is JupyterBook. The only minor pain point is that the rendering of the notebook in jlab is not perfect:

[agoose77]

Could you clarify if you're using jupyterlab-myst, or or just JupyterLab?

[fmaussion]

mmm plain jupyterlab. I'm starting to think that all my questions over the last year can be answered with: "just have your students install "jupyterlab-myst" !