slidev-addon-notecell

A Slidev addon that brings interactive Jupyter notebook cells to your presentations. Execute Python code, create visualizations, and demonstrate live coding directly in your slides.

Features

• 🚀 Interactive Code Execution - Double-click code cells to execute Python code
• 📊 Rich Output Support - Display plots, tables, images, and HTML output
• 🔄 Initialization Cells - Auto-run setup code when slides load
• 📐 Flexible Layouts - Vertical and horizontal code/output arrangements
• 🎨 Customizable Styling - Control colors, sizes, and spacing
• 👨‍🏫 Presenter Mode - Safe execution with warnings in presenter view
• 🌙 Theme Support - Works with all Slidev themes
• ⚡ Powered by Thebe - Built on the robust Thebe Core library

Installation

npm install slidev-addon-notecell

Basic Usage

1. Add to your Slidev presentation

In your slides.md frontmatter:

---
addons:
  - slidev-addon-notecell
---

2. Use the NoteCell component

# My Slide

<NoteCell class="w-full h-60">
```python
print("Hello from Jupyter!")
result = 2 + 2
print(f"2 + 2 = {result}")

3. Double-click to execute

Double-click the code cell during your presentation to execute the code and see the output.

Configuration

Jupyter Server Setup

You need a running Jupyter server. The default configuration expects:

• Base URL: /thebe/ (configurable via baseUrl prop)
• Token: `` (configurable via token prop)
• Path: /tmp/ (configurable via path prop)

如果 baseURL 使用默认值，则你还需要在 vite.config.ts 中，添加代理:

export default defineConfig({
    server: {
        proxy: {
            '/thebe': {
                target: 'http://127.0.0.1:8080/path',
                changeOrigin: true,
                ws: true,
                rewrite: (path) => {
                    // console.log('proxying:', path);
                    return path.replace(/^\/thebe/, '')
                }
            }
        }
    }
})

target 应该为JupyterLab 址到/lab/tree 之前的部分。比如，如果你能在 http://localhost:8080/course/fa/aaron/lab/tree/courseware/01.ipynb打开这个 notebook,那么，你就应该将 target 设置为 http://localhost:8080/course/fa/aaron

你也可以单独为每个 Notecell 设置 baseUrl，直接把它设置为绝对路径，比如 http://localhost:8080/course/fa/aaron。这种情况下，如果 jupyter lab 已设置为允许跨源访问，则可以不用代理。

Component Props

| Prop | Type | Default | Description | | ------------- | ------- | ---------------- | ---------------------------------------- | | init | Boolean | false | Auto-run cell when slide loads | | layout | String | "vertical" | Layout: "vertical" or "horizontal" | | hideOutput | Boolean | false | Hide output initially | | maxOutput | Boolean | false | Allow maximum output height | | outputWidth | String | "50%" | Width of output area (horizontal layout) | | outputMt | String | "-3.2rem" | Output margin top | | outputMl | String | "0" | Output margin left | | scaleImg | String | "100%" | Scale images in output | | color | String | "black" | Text color for output | | baseUrl | String | "/thebe/" | Jupyter server base URL | | token | String | "Qu@ntide2024" | Authentication token | | path | String | "/tmp/" | Notebook file path |

Examples

Basic Code Execution

<NoteCell class="w-full h-60">
```python
import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.figure(figsize=(8, 4))
plt.plot(x, y)
plt.title('Sine Wave')
plt.show()

Initialization Cell

<!-- This runs automatically when the slide loads -->
<NoteCell init class="w-full h-40">
```python
import pandas as pd
df = pd.read_csv('data.csv')
print("Data loaded!")

Horizontal Layout

<NoteCell layout="horizontal" outputWidth="60%" class="w-full h-80">
```python
import seaborn as sns
import matplotlib.pyplot as plt

# Create visualization
fig, ax = plt.subplots(figsize=(6, 4))
sns.scatterplot(data=df, x='x', y='y', ax=ax)
plt.title('My Plot')
plt.show()

Custom Styling

<NoteCell 
  layout="horizontal" 
  outputWidth="55%" 
  scaleImg="80%" 
  color="#2563eb"
  class="w-full h-80"
>
```python
# Your code here

Interactive Features

Execution

• Double-click any code cell to execute
• Toggle view between code and output by double-clicking again
• Status indicator shows "runnable" or "running" state

Presenter Mode

• Safe execution warnings in presenter view
• Prevents accidental code execution during presentation
• Prompts to run code in slide view instead

Jupyter Server Configuration

Local Development

# Start Jupyter server with token
jupyter lab --token=Qu@ntide2024 --allow-root --ip=0.0.0.0

Docker Setup

FROM jupyter/scipy-notebook

# Install additional packages
RUN pip install plotly seaborn

# Start with custom token
CMD ["jupyter", "lab", "--token=Qu@ntide2024", "--allow-root", "--ip=0.0.0.0"]

Custom Configuration

<NoteCell 
  baseUrl="http://localhost:8888/" 
  token="your-custom-token"
  path="/your/notebook/path/"
>
```python
# Your code

Styling

CSS Classes

The component uses these CSS classes that you can customize:

.thebe-code {
  /* Code cell styling */
}

.output-wrapper {
  /* Output area styling */
}

.wrapper-all {
  /* Container styling */
}

.horizontal-layout {
  /* Horizontal layout modifications */
}

Custom Themes

The component adapts to your Slidev theme automatically. You can override styles in your theme's CSS:

.slidev-addon-notecell .thebe-code {
  background: var(--slidev-code-background);
  border-radius: 8px;
}

.slidev-addon-notecell .output-wrapper {
  color: var(--slidev-code-foreground);
}

Troubleshooting

Common Issues

1. "Could not start thebe jupyter session"

   • Check if Jupyter server is running
   • Verify baseUrl and token configuration
   • Ensure server allows cross-origin requests

2. Code not executing

   • Double-click the code cell
   • Check browser console for errors
   • Verify Jupyter server connectivity

3. Output not displaying

   • Check if hideOutput is set to true
   • Verify the code produces output
   • Check for JavaScript errors

Debug Mode

Enable debug logging:

// In browser console
localStorage.setItem('thebe-debug', 'true')

Development

Setup

git clone <repository-url>
cd slidev-addon-notecell
npm install

Testing

# Run example presentation
npm run dev

# Build for production
npm run build

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Dependencies

• thebe-core: Jupyter integration
• crypto-js: Cryptographic utilities
• Vue 3: Component framework
• Slidev: Presentation framework

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

• Built with Thebe Core
• Inspired by Jupyter Notebooks
• Designed for Slidev presentations