Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

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

Answered by pawamoy
thomasmarwitz asked this question in Q&A
Discussion options

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)
You must be logged in to vote

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, ...

Replies: 1 comment 3 replies

Comment options

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 🙂

You must be logged in to vote
3 replies
Comment options

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!

Comment options

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

Comment options

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

Answer selected by thomasmarwitz
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Category
Q&A
Labels
None yet

AltStyle によって変換されたページ (->オリジナル) /