Integration with Jupyter Notebooks (via mkdocs-jupyter plugin) possible?

[thomasmarwitz]

Cf. danielfrg/mkdocs-jupyter#236

Context: We use jupyter notebooks as means to document use cases. Sometimes, we wanna link to the API documentation.

The issue is we render the notebook using nbconvert and it doesnt know its part of mkdocs. I imagine there is a way to maybe pass the MD to mkdocs so it handles those references.

The markdown cells are turned into HTML without mkdocs seeing or processing them.

@pawamoy
As the author of mkdocstrings python and as you have profound mkdocs knowledge, how feasible is this feature request in particular:

• The integration with another plugin, in this case yours
• The integration with general mkdocs (this is probably easier and would allow to use markdown links such as []() or admonitions)

[pawamoy]

Hello @thomasmarwitz 🙂

That depends on how nbconvert works, how we can hook into it, or how much mkdocs-jupyter relies on it. Essentially, since mkdocs-jupyter is a MkDocs plugin, it definitely has access to the Python-Markdown Markdown instance created by MkDocs and used to convert Markdown to HTML. So it could use it to convert Markdown cells, and this md object would have the mkdocstrings extension (and by extension, no pun intended, the mkdocs-autorefs extension too) registered, so mkdocstrings instructions (:::) and autorefs cross-references ([title][object.path]) would work (as well as all other markup supported by extensions configured in mkdocs.yml). Maybe with a few limitations, or hacks to apply. Happy to help if you want to try going in that direction 🙂

[thomasmarwitz]

Thanks for your detailed answer! This sounds indeed promising, this plugin system is really thought out.

I have some exams coming up so I'll probably tackle this in a few weeks. I'll reference you in the issue or PR once I've pieced something together. If that doesn't work at all I'll reach out :) thanks for being so kind!

[pawamoy]

Sounds good! You're welcome 🙂 Pinging me is fine, don't hesitate 😄

[thomasmarwitz]

Just writing to here to let you know that I had postpone this until I have some more free time :/