Fragment Identification Syntax for Jupyter (linking to cells in document)
- Dominant language
- Python
- Stars
- 313
- Forks
- 176
- PR merge metrics
- No merged PRs in 30d
Description
It is currently possible to link directly to specific markdown heading in notebook or to any HTML element with `id` property via the use of URL [fragment identifier](https://www.w3.org/TR/html401/intro/intro.html#fragment-uri) to automatically scroll to such a heading or element (e.g. via destination anchor).
There is currently no way to scroll to other elements of the notebook. https://github.com/jupyter/nbconvert/issues/1862 and https://github.com/executablebooks/jupyter-book/issues/1812 proposed to allow linking to specific cells in the Jupyter notebooks. Elements which we may want to link to are:
- cells (and ranges of cells)
- outputs (cell can have more than one output),
- sections inside of outputs (imagine large table which is [lazy-loaded/paginated](https://github.com/jupyter/notebook/issues/2049))
- fragments of the editor (potentially useful for applications in education)
Fragment Identification Syntax is a way of defining how to recognise which element is referred to in the Fragment Identifiers. Adopting one for Jupyter notebooks will:
- harmonise how frontends and converters (e.g. nbconvert) transform headings to fragments (there is a lot of choices in escaping problematic characters and dealing with duplicated headings (see [notebook#77](https://github.com/jupyter/notebook/issues/77))
- allow referring to arbitrary part of the notebook in a future-proof way (so that we can add additional targets later thanks to scoping)
- disambiguate elements bearing the same name, for example a cell with ID "example" and a heading "example" (human-readable Jupyter cell IDs are permitted and are proposed [as default](https://github.com/jupyter/nbformat/issues/218) in the future)
Formats with Fragment Identification Syntax include:
- text/csv ([RFC 7111](https://www.rfc-editor.org/rfc/rfc7111#section-3)) which allows to link to a specified:
- row: `a.csv#row=1`, range of rows `a.csv#row=5-7`, use wildcard for last row `myacsv#row=5-*`,
- column `a.csv#column=2` (and ranges, as above), or
- cell `a.csv#cell=1,2` (as above),
- text/plain ([RFC 5147](https://datatracker.ietf.org/doc/html/rfc5147#section-3)) includes an optional integrity check in case if document has changed (md5 or length-based) and allows to link to a specified:
- line: `a.txt#line=1`, range of lines `a.txt#line=10,20`,
- character: `a.txt#char=100` (or range, as above)
- application/yaml ([RFC draft](https://www.ietf.org/archive/id/draft-ietf-httpapi-yaml-mediatypes-03.html#name-fragment-identification)):
- alias nodes: `a.txt#*alias`
For more examples see Wikipedia: [URI fragment](https://en.wikipedia.org/wiki/URI_fragment#Examples).
The proposed way forward is to:
- keep current behaviour for headings (auto-generated IDs point to the heading/element without any special prefix by default)
- define syntax for cell fragment as the fundamental unit of the notebook (e.g. `cell=my-cell-id` or `cell-id=my-cell-id`)
- create a PR with reference implementation in JupyterLab (and Notebook v7), nbconvert and jupyter-book
This proposal result in a very limited backward incompatibility, this is a heading with `cell=` prefix would now be resolved to a cell instead of such a heading. We could support `heading=` target to allow to disambiguate.
Questions:
1. do we want a JEP for this proposal?
2. should we have multiple ways of referring to a cell? Cell IDs are an obvious way forward, but we could also support syntax like `nth-cell=3` or `nth-code-cell=2`?
Of note, equals sign is allowed in identifiers in HTML 5 but not in HTML 4; we could consider using a colon instead (`cell:my-cell`, but using an equals sign seems in line with other formats). Spaces are always forbidden in identifiers.
Contributor guide
Research direction
Start by reviewing the proposed fragment syntax and the linked nbconvert and Jupyter Book discussions. Compare how JupyterLab, Notebook v7, nbconvert, and jupyter-book would support the syntax; done would require an agreed design and reference implementations across those projects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- jupyter-notebook, python
- Domain
- developer-experience, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100