Give notebook cells stable deep-link anchors - #2975
Conversation
🦋 Changeset detectedLatest commit: ea379f0 The changes in this PR will be included in the next version bump. This PR includes changesets to release 8 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
Thanks for this PR @Darshan808! I'll take a look this week unless someone gets in first! |
krassowski
left a comment
krassowski
left a comment
There was a problem hiding this comment.
Can it use #cell-id=my-cell-id schema to align with the format used by nbconvert and JupyterLab?
|
Yes, ultimately we will support |
|
@Darshan808 can you clarify your relationship with Jupyter Book? Your wording here
slightly implies that you have decision making authority for the project. I think this is just a nuance of language, and I'm very appreciative of your contribution here — but I want to understand and clarify any confusion as the distinction is important. |
|
That was just an imprecise choice of words on my part. I don't have any decision-making authority for Jupyter Book. |
|
Disclosure: I work with @Darshan808
I don't think one can speak for the broader community either, but certainly for some parts of the userbase as to what they seem desirable (i.e. having a stable way to link to different parts of a notebook across Jupyter interfaces). I think what would be fair to say in the original comment would be:
I for one was reaching out to a few members of MyST and JupyterBook community for years, sadly this was previously blocked by complexity of implementing this in Sphinx and possibly lack of impetus:
In the process multiple community members engaged with the discussion, supporting the idea or welcoming the PRs as seen in the issues linked above (Chris Sewell, Chris Holdgraf and Rowan Cockett), which might give the impression that there is some level of agreement in the community. Of course, whatever was expressed by individuals years ago does not imply a project-level agreement at the time, nor that they would still support this given the time that has passed. @agoose77 apologies that this was misinterpreted and misrepresented above. |
|
@Darshan808 @krassowski thanks both for clarifying things! I really do not want this to get overblown — I just wanted to clear up what was being said. I wasn't aware that @krassowski works with @Darshan808, this adds some helpful context. On this PR and the goals — Jupyter Book is a Jupyter subproject and we're very keen to ensure that we provide a good integration with the conventions and tooling like Jupyter Lab. So, I wholeheartedly agree with the idea from @krassowski that Jupyter Book is keen to move this forward. ❤️ |
|
Is there anything I could help with to move this forward? |
|
@krassowski good timing — I was just circling back. Let me pick this up tomorrow (sets reminder). |
The `block.id` is a legacy "stash" that we can remove. Prefer directly propagating cell IDs like this.
Co-authored-by: darshan <pranishpoudel10@gmail.com>
|
Thank you so much for this PR! I've updated this PR to simplify the label propagation given my knowledge of our intention behind labels and how this state is managed. It was a good opportunity to clean something up! |
| children: children as any, | ||
| }; | ||
| const cellId = (cell as { id?: unknown }).id; | ||
| if (typeof cellId === 'string' && cellId.length > 0) { |
There was a problem hiding this comment.
Now we only handle cell IDs during parsing of an ipynb file. The intention here is to avoid stashing something — we can directly set the ID and html_id.
| if (block.identifier) { | ||
|
|
||
| // Did the user set a label? Choose to only propagate IDs if so. | ||
| const hasExplicitLabel = typeof block.label === 'string'; |
There was a problem hiding this comment.
In choose to check the final block.label, because that feels slightly more explicit than the intermediate block.data
|
Thank you! |
3 participants
Fixes #518
Description
Right now, deep-linking to notebook cells is unreliable. We were discarding the nbformat cell id and falling back to a random nanoid, so
#<id>links changed on every build.This PR promotes notebook cell ids to stable anchors:
notebook.tspreservescell.idwhen reading.ipynbfiles.blocks.tsmaps it toidentifier(normalized) andhtml_id(verbatim).myst-to-htmlemits the anchor on block containers, so static HTML exportsget stable links too.