Fragment Identification Syntax for Jupyter (linking to cells in document) #317
Comments
|
To expand on things folk have wanted to point at in a client-agnostic way:
Of particular note here is choosing something that can be made to work with the web annotation data model. If these things are This is definitely a JEP-level concern, but could certainly be demonstrated first in a Lab4/Notebook7/nbconvert compatible extension before going for something in core... previous efforts have foundered on trying to integrate too deeply and do too much. |
Maybe the position inside of output is out of scope for the fragment syntax specification; instead we could:
This way we avoid re-inventing the the syntax for specific data types. For source code we can use
Some thoughts here:
|
Much like when cell ids became a thing (but not output ids), i feel like this would be a significant change to handle for implementations, and doing it piecemeal wound't be as much fun.
I'd wager because there's not JSON fragment syntax. The closest is JSON pointer, but it's a hair underpowered, as it lacks the ability to do attribute lookups. This means a cell would have to be Inventing a new syntax would be very frustrating. But at the end of it, if a notebook-derived document can't refer back to the logical location within a (potentially nbconvert-mangled) document, I don't know if we've moved the state-of-the-art forward. If we did pick from one of the many non-standard JSON reference mechanisms ( |
|
I though that GeoJSON users would be interested in pointing to a specific position on map, not to a node in JSON? That wold be something like Summarising what I see so far:
|
|
For what it is worth, I implemented fragment id's for all of the editors in CoCalc recently. The format I used for our Jupyter notebooks is That's it. Thanks for thinking through a format for more refined information! I'll attempt to follow what you do for any extensions, rather than inventing something new (except I'm sticking with #id rather than #cell-id). |
|
|
@westurner thank you for pinging interested parties and very useful links. Do you think that advancing with One slightly-technical question to all: if we go forward with @gwincr11 this might be of your interest too. |
|
@krassowski thanks for bringing this to my attention. I have been looking at a similar issue, with mapping content to a Python notebook. Cell id is useful, I am curious if a more granular approach would be helpful though. One thing that is super helpful in the GitHub ui is linking directly to a block of code, this is granluar down to the line being discussed. I would love a tool that allowed for adding into the notebook structure easily across platforms without the content needing to be in the notebook json structure. It maybe interesting to consider something like a Javascript source map, this would give very granular access to the line level potentially or even character. There are a number of json mapping tools in the python echo system, here is a stack overflow discussing this very idea. https://stackoverflow.com/questions/55684780/get-line-number-while-parsing-a-json-file My thinking around this is that it maybe nice to tie content to the rich text view of the notebook and makes it portable with the notebook, without needing to be part of the structure, since a consumer can map features into the notebooks structure at render time. For example you could create a commenting system that worked with any third party tooling, GitHub, GitLab etc and since the comments could map to the underlying json structure you could bring PR review comments into any plugin you wanted. |
Web annotations may also be a good way to accomplish this... I am wondering how portable it maybe to other plugins? I do like that is it an open standard though 😄 |
|
I have a platform that uses URLs to embed code: https://docs.metapage.io/docs For a lot of the components (that are simply URLs/websites), I use the hash part of the URL, but re-use the query param format:
This way the hash parts can be very big without sending all that code to the server. The important bit is that it contains a hash fragment and hash query params. Whatever schema is decided here, it would be great if I could keep my hash |
It is currently possible to link directly to specific markdown heading in notebook or to any HTML element with
idproperty via the use of URL fragment identifier 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. jupyter/nbconvert#1862 and jupyter-book/jupyter-book#1812 proposed to allow linking to specific cells in the Jupyter notebooks. Elements which we may want to link to are:
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:
Formats with Fragment Identification Syntax include:
a.csv#row=1, range of rowsa.csv#row=5-7, use wildcard for last rowmyacsv#row=5-*,a.csv#column=2(and ranges, as above), ora.csv#cell=1,2(as above),a.txt#line=1, range of linesa.txt#line=10,20,a.txt#char=100(or range, as above)a.txt#*aliasFor more examples see Wikipedia: URI fragment.
The proposed way forward is to:
cell=my-cell-idorcell-id=my-cell-id)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 supportheading=target to allow to disambiguate.Questions:
nth-cell=3ornth-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.The text was updated successfully, but these errors were encountered: