Integration with Jupyter Notebook

[fgebhart]

Hey 👋

I started exploring the capabilities of mkdocs and mkdocs-material recently and I'm amazed by the multitude of available features and possible customizations! As I intend to use mkdocs-material for writing technical blog posts in the Python ecosystem, I also have a big interest in rendering jupyter notebooks within my static website. But so far I'm struggling to achieve this and am looking for some guidance.

What I'm basically trying to achieve is: I want to include a jupyter notebook (or a few/ a single cell(s)) into my markdown file, so that I'm still able to make use of the flexibility of mkdocs-material markdown capabilities like Admonitions, Diagrams, Footnotes, Metadata, etc.

A few ideas:

1. There are libraries which aim on integration jupyter notebooks into the static website (mkdocs-jupyter, mknotebooks). However, these libraries seem to include an entire ipynb file by rendering it completely. As far as I can see there is no option for combining the notebook rendering capabilities with the flexibility of mkdocs-material.
2. One could probably come up with a custom CSS style sheet to allow for custom superfence code blocks which are rendered in the typical jupyter style (see for example this). I found this approach to be feasible in this issue, but this approach feels rather like a custom workaround for which I first would need to dive deeper into css.
3. I learned about the existence and growth of projects like JupyterLite, wasm and Pyodide recently. However, I'm not a webdev and have probably no hunch about the efforts needed to integrate tools like these with mkdocs-material.

I would appreciate any kind of feedback on whether I'm totally heading in the wrong direction, some of these ideas would make sense or if I missed a different approach completely. Thanks in advance!

[squidfunk]

Unfortunately, I'm not a Jupyter user. I hope some Jupyter users could share their recipes. Other than that, you might use the search to find some possible directions, as this topic was discussed a few times.

[fgebhart]

Thanks for your view on things. Unfortunately I did not make much progress yet. I will share my findings anyway, maybe it is helpful for anyone.

I believe the most productive integration currently existing is to use mkdocs-jupyter and integrate entire jupyter notebooks. It allows to nicely render the individual cells and their output. This comes with a few drawbacks though:

• Using markdown cells in such a notebook, does not offer the entire mkdocs-material markdown world like admonitions etc.
• Using a entire jupyter notebook does not allow to specify the metadata of the document

Not using admonitions within a notebook is okay to me, but not being able to set metadata like tags is a pity. Could anyone think of a workaround to this issue? Something like a auto-redirect where a .md file (containing title, description and tags) exists and is listed in the nav section, but when clicking on it in the toc in the browser, it will auto re-direct to the jupyter-notebook. This could potentially allow for using tags (and a tag index page) with jupyter notebooks (while of course not displaying the tags in the top of the notebook, but that is acceptable for me).

[MatthewSteen]

JupyterBook is a better choice than MkDocs for what you want.

[squidfunk]

That, or somebody invests the time and writes a plugin that allows for doing the same things. There's no reason this cannot be done with MkDocs, it's just that nobody hasn't done it yet. The MkDocs plugin system is very simple and extensible.

[pascalwhoop]

High level I'd think this could work:

posts/
    some_article/
        config.yaml
        notebook.ipynb

Then in the config.yaml you put the front-matter, the notebook.ipynb gets rendered as usual by mkdocs-jupyter and the blog body would use that output. wdyt?

[BwL1289]

Interested