Linking or Cross-Referencing in Notebooks

Since linking or cross-referencing question has come up from time-to-time, let me try document this here, including a known issue that is currently in the backlog as of Dec 22, 2020. I’ll be sure to update this blog post when a new update comes up 🙂

When writing a notebook, it can be very handy to be able to refer to a specific part to a notebook and allow the readers to jump to that part, i.e linking or anchoring. Using this technique, you can also create an index list or a table of contents or cross-referencing to parts of other notebooks too. Check out my demo notebook for this linking topic, from MsSQLGirl Github Repo.

Here’s an example of what you can build through linking / cross-referencing.

Linking to Notebook Headers

Azure Data Studio adopts the Github Flavored Markdown (GFM) standard, including the syntax for header links. This means that headers automatically get “IDs”.

1. As documented by GitLab, the IDs for headers are generated from the header name:
2. All text is converted to lowercase.
3. All non-word text (such as punctuation or HTML) is removed.
4. All spaces are converted to hyphens.
5. Two or more hyphens in a row are converted to one.
6. If a header with the same ID has already been generated, a unique incrementing number is appended, starting at 1.

Example of the header markdown lines and their respective links:

Note that the emoji processing happens before the header IDs are generated, so the emoji is converted to an image which is then removed from the ID.

Linking to other notebook parts in markdown

Linking to other parts to your notebook, i.e cross-referencing, is possible in Azure Data Studio. The simplest way I can find right now is to mark the parts the <a id=some-id /> and use the same notation that you learned above, i.e. #some-id. I’d recommend not using punctuations when creating an id.

For example, you can add this ID before a “blocked quote”:

> <a id="some-id" /> **Tip**: Hello World

To refer to it, you simply type the following:

My greeting is [here](#some-id).

Linking to another notebook’s parts in markdown

Linking to another notebook in the same directory is like this:

Check out my [other notebook](./OtherNotebook.ipynb)

Linking to another notebook in the parent directory looks like this (with the double dot):

Check out my [other notebook in my parent directory](../ParentNotebook.ipynb)

With the above two examples, Azure Data Studio will just load the notebook and show you the top of the notebook.

Now, to link to other part of notebook, say a header it would be simply appending the header id as shown below. As of 22 Dec 2020, this specific feature of linking to other parts of notebook is available in Azure Data Studio v1.26.0-insider build (download).

Check out my [other notebook's heading](./OtherNotebook.ipynb#ice-cream)

Or

Check out my [other notebook in my parent directory](../ParentNotebook.ipynb#lets-have-boba)

Would this rule apply for .md files?

You can follow the rules above for .md files. When you do so, cross-referencing works on both Azure Data Studio and GitHub too. Check out my md file example on GitHub.

Known issues

There is a known edge-case offset issue on linking / cross-referencing within notebooks – and not .md files – in Azure Data Studio, which is currently tracked on GitHub. Please feel free to try and also comment how it works (or doesn’t work for you). If it doesn’t work for you, please thumbs up on the GitHub issue so that we can prioritize this. The more people we have trying this, the more we can make it better 🙂 Fixed on ADS v1.25.2, see Azure Data Studio Release Notes.

Not all Jupyter Notebook viewers support this syntax. For example, the Notebook viewer in GitHub and Jupyter Notebook Renderer (extension) in Azure DevOps do not support linking or cross-referencing.