JupyMD for Obsidian

Enables Jupyter notebook functionality in Obsidian. Make markdown files behave like .ipynb notebooks, with live code execution, rich output rendering, and bidirectional syncing between .md and .ipynb files.

Integrate your programming notes into Obsidian

With JupyMD you can:

• Run Python code
• Create plots with matplotlib
• Conduct data analysis with pandas dataframes
• Build machine learning models with sklearn and pytorch
• And much of what you would typically use a Jupyter notebook for

... all in your Obsidian vault!

Use-cases:

Machine learning workflow

Visualising fractals with matplotlib

Features

• Notebook Conversion
  • Convert existing notes in Obsidian to .ipynb files via Jupytext
  • Convert existing Jupyter notebooks (.ipynb) to Markdown notes (.md) via Jupytext
• Bidirectional Updates – Changes in Obsidian or Jupyter automatically sync between .md and .ipynb files
• Execute Code – Run code blocks in Obsidian with output captured below each block, regardless of viewing mode
• Persistent Execution Environment – Variables and imports defined in one code block are remembered by the following code blocks
• True Jupyter Sync – Executed code blocks automatically update output metadata in linked .ipynb file
• Persistent Output Rendering – Executed code outputs stay visible after restart and sync to .ipynb file
• Rich Output – Support for matplotlib plots and pandas dataframe outputs

Prerequisites

• Python
• Jupyter Notebook pip install notebook
• Jupytext pip install jupytext
• Matplotlib pip install matplotlib

Getting started

Download the plugin through the Obsidian community plugin browser and enable it.

Quick Setup

The easiest way to setup everything is by clicking the "Run Quick Setup" button on the settings page. This will create a virtual environment called .jupymd on your vault root, configure it as the interpreter, and install all necessary dependencies.

To install any additional dependencies, run the following on a terminal:

<path_to_interpreter> -m pip install <library>

Manual setup

You can use any existing interpreter by pointing to its location.

The default settings assume Python is in your system's PATH. It is highly recommended to set the interpreter to a virtual environment instead.

In a directory where you want your virtual environment to be stored in:

python -m venv <venv>

To use the virtual environment within JupyMD, go to the plugin settings, and insert your venv interpreter location:

/<venv>/bin/python # for Linux/MacOS
\<venv>\Scripts\python.exe # for Windows

Afterwards, restart Obsidian. Once loaded, go back to the JupyMD settings, and click on the "Install Libraries" button. This will install Jupytext and Matplotlib to your specified Python interpreter.

To convert a note to a Jupyter notebook

Execute the following command on a note you want Jupyter notebook capability on:

JupyMD: Create Jupyter notebook from note

This will create an .ipynb file with the same file name as the current note on the file directory, and will transform your Python code blocks into interactive code blocks. Your note will now behave like a Jupyter notebook, and sync its contents automatically to the .ipynb file. You may choose to ignore the created .ipynb file completely, as its functionality will be mirrored in Obsidian.

To convert a Jupyter notebook to a note

Move your Jupyter notebook to your vault. Executing the following command will list out all .ipynb files within your vault which you can select to convert into a note:

JupyMD: Create note from Jupyter notebook

This will create a Markdown note (.md) with the same file name as the notebook in the same directory where the Jupyter notebook is.

Contributing

Please read the contribution guidelines if you want to contribute to JupyMD.

This project was originally built to solve a personal problem, and it's still in an early stage. Feedback, bug reports, and pull requests are all welcome and appreciated!

[!NOTE] JupyMD currently supports Python execution only.

Future versions will expand language support, though this feature is not yet in active development. Your help is appreciated, feel free to open an issue or submit a pull request if you would like to contribute!

JupyMD is an independent project and not affiliated with Project Jupyter or Obsidian.