Simple way to style notebook cells using cell tags

[psychemedia]

One of the likely use cases of RetroLab is in education, where the simplified UI helps foreground the notebook content rather than the development/execution environment.

With the rising popularity of Jupyter Book, it is not hard to imagine users being directed to a live notebook view from a Jupyter Book HTML page.

In many cases, the notebook view will be styled to include special content blocks, such as styled warning or explanation blocks.

Many of the special content blocks rely on specialised markdown, although its not hard to imagine a processing step where rather than create a tagged backticked block, a cell is tagged in a source notebook document and a processing step then generates the appropriate backticked markdown block.

Whilst style can be added to markdown content via HTML tags, this requires both a knowledge of HTML, as well as cluttering the markdown with HTML code. Inconsistency might also creep into even the same notebook in the form of different HTML expressions being used in different markdown cells to achieve the same presentation effect.

In the classic notebook, it's relatively easy to create a notebook extension that uses shipped bootstrap CSS to annotate notebooks cells in the UI based on cell tags (for example, innovationOUtside/nb_extension_tagstyler.

Style can also be applied to other levels of the cell HTML (for example, innovationOUtside/nb_extension_empinken).

It would be useful to be able to tag cells in the RetroLab UI and have those tags trigger particular specific predefined style effects. Visual highlighting of content and cells could then be presented consistently in a live notebook view as well as in a rendered Jupyter Book view. Whilst there may be slight differences in the actual rendering, colour theming and the general style of presentation should be consistent, or at least, not inconsistent.

[welcome]

Thank you for opening your first issue in this project! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please try to follow the issue template as it helps other other community members to contribute more effectively.

You can meet the other Jovyans by joining our Discourse forum. There is also an intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[jtpio]

Thanks @psychemedia.

Probably this could be implemented as a prebuilt lab extension? Since RetroLab reuses the same notebook widget as JupyterLab, the extension would work in both lab and retro (so it's not specific to Retro).

The classic notebook includes the bootstrap CSS so it's indeed possible to reuse these handy colors (alter-warning, alert-danger and so on). JupyterLab doesn't use the bootstrap CSS but an extension could include a subset of it. Or it might not even be necessary and the colors could be defined as CSS variables / classes.

So ideally we could port the nbextension to JupyterLab. There is a WIP PR to simplify the JavaScript cookiecutter to hopefully make the extension authoring easier: jupyterlab/extension-cookiecutter-js#38

Then the lab extension could live in the jupyterlab-contrib organization for better visibility: https://github.com/jupyterlab-contrib

Once published, pip install jupyterlab-tagstyler would install the extension on disk, and retro would pick it up automatically.

[psychemedia]

If cells are all rendered the same way in JupyterLab and RetroLab, then that would make sense, and would presumably also allow other UIs built from the same framework components to add styling on a similar basis.

A simple extension that demonstrates how to:

• iterate over cells;
• inspect metadata/tags;
• style cells, and/or
• manipulate cell metadata, and/or
• manipulate cell contents

would cover the basics for a wide range of extensions targeted at making the notebook rendering sensitive to/reactive to the notebook metadata.

Coming up with a sensible set of tags (eg drawing on tag naming and usage across various projects and looking for emerging consensus among them) would also be important (I already made a start on that somewhere, IIRC...Hmm, I wonder where those notes went?!).

[psychemedia]

Re: building federated extensions, is there a Github Action that does that? That could be a handy step towards simplifying the creation and publication of extensions? (Simplifies creation by encouraging a user to use a templated set of required files and directory structure, perhaps supported by documentation associated with the Action that bridges the more general extension template documentation; and simplifies publication by automating the build therefrom. Though it would bring with it the overhead of requiring eg a Github Account to host the automation, of course...)

[jtpio]

A simple extension that demonstrates how to:

Normally there should be a couple of pointers in this repository: https://github.com/jupyterlab/extension-examples

Maybe they don't cover all the items listed above, so it might require looking at other places or the API docs to learn about the lab API.

Re: building federated extensions, is there a Github Action that does that? That could be a handy step towards simplifying the creation and publication of extensions? (Simplifies creation by encouraging a user to use a templated set of required files and directory structure, perhaps supported by documentation associated with the Action that bridges the more general extension template documentation; and simplifies publication by automating the build therefrom. Though it would bring with it the overhead of requiring eg a Github Account to host the automation, of course...)

The cookiecutters provide exactly this. They are templates for creating new extensions. And they generate prebuilt / federated extensions by default.

Moreover there is now the Jupyter Releaser project to automate releases: https://github.com/jupyter-server/jupyter_releaser
Extensions generated from the cookiecutter should already be compatible with the releaser. The following extensions can serve as an example:

• https://github.com/jupyterlab-contrib/jupyterlab-cell-flash
• https://github.com/jupyterlab-contrib/jupyterlab-link-share
• https://github.com/jupyterlab-contrib/jupyterlab-plugin-graph

So I would say all the tools and templates should already be there. Maybe what is needed is a more accessible Getting Started guide, that would be focused on JavaScript.

[psychemedia]

Thanks for that pointer. It's been some time since I checked that repo. I didn't offhand see an example that does what I think is needed so I posted a related issue there and will close this one: jupyterlab/extension-examples#182