Jopyter Notebook - Joplin Plugin

Add runnable Python code blocks to your Joplin notes!

Jopyter brings Jupyter notebook functionality directly into Joplin, allowing you to write, execute, and display Python code with rich output including plots, images, and formatted text right in your notes.

Features

• Execute Python code blocks directly in Joplin notes
• Rich output support including:
  • Text output (stdout/stderr)
  • Images and plots (matplotlib, seaborn, etc.)
  • HTML and Markdown rendering
  • Error handling with full tracebacks
• Multiple execution modes:
  • Run all Python blocks in a note
  • Run the current block (cursor-based)
  • Run specific blocks with custom kernels
• Persistent kernels for maintaining variable state between executions
• Keyboard shortcuts for quick execution
• Context menus and toolbar integration
• Customizable settings for Python path and kernel configuration
• Automatic demo notebook with comprehensive examples and tutorials

Prerequisites

Before using Jopyter, ensure you have:

1. Python 3.6+ installed on your system
2. Required Python packages:

   pip install jupyter_client ipykernel

Installation

1. Download the latest .jpl file from the releases page
2. In Joplin, go to Tools → Options → Plugins
3. Click Install from file and select the downloaded .jpl file
4. Restart Joplin
5. Demo notebook: A "Jopyter Notebook" folder will be automatically created at the top level with a comprehensive demo note containing examples and tutorials

Configuration

After installation, configure Jopyter:

1. Go to Tools → Options → Plugins → Jopyter
2. Set the following options:
   • Python executable: Path to your Python interpreter (e.g., /usr/bin/python3)
   • Default kernel name: Kernel name to use (default: python3)
   • Working directory: Optional working directory for code execution

Platform-Specific Python Paths

• Linux: /usr/bin/python3 or ~/miniconda3/envs/myenv/bin/python
• macOS: /opt/homebrew/bin/python3 or /usr/local/bin/python3
• Windows: C:\Users\you\miniconda3\envs\myenv\python.exe

Usage

Creating Python Code Blocks

Method 1: Using the Menu

1. Place your cursor where you want the code block
2. Go to Tools → Jopyter → Insert Python code block
3. Or use the keyboard shortcut: Ctrl+Alt+P (Windows/Linux) or Cmd+Alt+P (macOS)

Method 2: Manual Creation

Create a code block with the following syntax:

```python kernel=python3
# Your Python code here
print("Hello, Jopyter!")
```

Executing Code

Run All Python Blocks

• Menu: Tools → Jopyter → Run all Python blocks
• Toolbar: Click the Python icon in the editor toolbar
• Keyboard: Use the command palette (Ctrl+Shift+P / Cmd+Shift+P)

Run Current Block

• Keyboard: Ctrl+Shift+Enter (Windows/Linux) or Cmd+Shift+Enter (macOS)
• Context Menu: Right-click in a Python block → "Run current Python block"
• Menu: Tools → Jopyter → Run current Python block

Advanced Features

Custom Kernels

Specify different kernels for different code blocks:

```python kernel=myenv
import pandas as pd
# This uses the 'myenv' kernel
```

Working Directory

Set a custom working directory in the plugin settings to run code from a specific location.

Rich Output Examples

```python
import matplotlib.pyplot as plt
import numpy as np

# Create a simple plot
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.plot(x, y)
plt.title('Sine Wave')
plt.show()
```

Managing Outputs

• Clear all outputs: Tools → Jopyter → Clear all Jopyter outputs in note
• Restart kernel: Tools → Jopyter → Restart Python kernel
• Create demo notebook: Tools → Jopyter → Create Jopyter demo notebook (creates the tutorial notebook)
• Force create demo notebook: Tools → Jopyter → Force create Jopyter demo notebook (recreate) (deletes existing and creates fresh)
• Find demo notebook location: Tools → Jopyter → Find Jopyter demo notebook location (shows where the notebook is located)
• Open demo notebook: Tools → Jopyter → Open Jopyter demo notebook (opens the demo note)

Screenshots

To help users understand how to use Jopyter, please take the following screenshots:

1. Plugin Installation

File: screenshots/installation.png

• Screenshot of Joplin's plugin installation dialog
• Show the "Install from file" button and file selection

2. Plugin Settings

File: screenshots/settings.png

• Screenshot of Tools → Options → Plugins → Jopyter
• Show the three configuration fields:
  • Python executable path
  • Default kernel name
  • Working directory

3. Menu Integration

File: screenshots/menu.png

• Screenshot of the Tools → Jopyter menu
• Show all available commands:
  • Insert Python code block
  • Run all Python blocks
  • Run current Python block
  • Restart Python kernel
  • Clear all Jopyter outputs in note

4. Toolbar Button

File: screenshots/toolbar.png

• Screenshot of the editor toolbar
• Highlight the Python icon button for running all blocks

5. Context Menu

File: screenshots/context-menu.png

• Screenshot of right-clicking in a Python code block
• Show the context menu options for Jopyter

6. Basic Code Execution

File: screenshots/basic-execution.png

• Screenshot of a simple Python code block before execution
• Show the code and the output after running

7. Rich Output Example

File: screenshots/rich-output.png

• Screenshot showing matplotlib plot output
• Include both the code block and the rendered plot

8. Error Handling

File: screenshots/error-handling.png

• Screenshot of a Python code block with an error
• Show the error output with traceback

9. Multiple Code Blocks

File: screenshots/multiple-blocks.png

• Screenshot of a note with multiple Python code blocks
• Show different execution states (some run, some not)

10. Keyboard Shortcuts

File: screenshots/keyboard-shortcuts.png

• Screenshot of Joplin's keyboard shortcuts settings
• Highlight the Jopyter-specific shortcuts

Keyboard Shortcuts

| Action | Windows/Linux | macOS | |--------|---------------|-------| | Insert Python code block | Ctrl+Alt+P | Cmd+Alt+P | | Run current Python block | Ctrl+Shift+Enter | Cmd+Shift+Enter |

Troubleshooting

Plugin Crashes on Startup

If Joplin crashes when starting with Jopyter enabled:

1. Check Python installation: Ensure Python 3.6+ is installed
2. Install required packages:

   pip install jupyter_client ipykernel

3. Verify Python path: Check that the Python executable path in settings is correct
4. Check Joplin logs: Enable developer tools (Help → Toggle Developer Tools) to see error messages

Code Execution Issues

• Module not found: Install required Python packages in your environment
• Permission errors: Check that the working directory is accessible
• Kernel issues: Try restarting the kernel or using a different kernel name

Output Not Displaying

• Images not showing: Ensure matplotlib/seaborn plots use plt.show()
• HTML not rendering: Check that the output is valid HTML
• Text formatting: Use proper markdown syntax in your output

Development

Building from Source

1. Clone the repository:

   git clone https://github.com/Dubascudes/JopyterPlugin.git
   cd JopyterPlugin

2. Install dependencies:

   npm install

3. Build the plugin:

   npm run dist

4. The built plugin will be in the publish/ directory

Project Structure

src/
├── index.ts          # Main plugin logic
├── editor.ts         # CodeMirror editor integration
├── manifest.json     # Plugin manifest
└── python/
    └── bridge.py     # Python-Jupyter bridge script

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Website: willenglish.tech

Changelog

v1.0.0

• Initial release
• Basic Python code execution
• Rich output support
• Multiple execution modes
• Keyboard shortcuts and context menus
• Customizable settings

Made with ❤️ for the Joplin community