notebook-mdx

A powerful remark plugin for rendering Jupyter notebooks in MDX with authentic styling, syntax highlighting, and full cell type support.

✨ Features

• 🎯 Authentic Jupyter styling - Matches real Jupyter notebook appearance
• 🎨 Syntax highlighting - Full language support with highlight.js
• 📊 All cell types - Code, markdown, and raw cells
• 🔧 TypeScript ready - Full type safety and IntelliSense
• ⚡ Fast rendering - Optimized for performance
• 🌐 Multi-language - Cell-level language detection
• 🖼️ Image support - PNG, JPEG, GIF, and SVG outputs
• 📖 Clean syntax - Simple directive-based usage

📦 Installation

npm install notebook-mdx remark-directive

🚀 Quick Start

1. Configure Your MDX Setup

Add the remark plugin to your MDX configuration:

import remarkDirective from 'remark-directive';
import { remarkNotebookDirective } from 'notebook-mdx/server'; 

// ...
  remarkPlugins: [
    remarkDirective, 
    remarkNotebookDirective, 
  ],
// ...

2. Import the components

import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';
import { NotebookCodeCell, NotebookLoader, NotebookMarkdownCell, NotebookStyles } from 'notebook-mdx'; 

const notebookComponents = {  
  NotebookCodeCell, 
  NotebookLoader, 
  NotebookMarkdownCell, 
  NotebookStyles 
}; 

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    ...components
    ...notebookComponents, 
  } as MDXComponents;
}

3. Use in Your MDX Files

That's it! Now you can use notebook directives directly:

# My Article

::notebook{file="./example.ipynb"} 

More content here...

::notebook{file="./demo.ipynb"}

🎨 Directive Options

💡 Usage Examples

Basic Usage

:::notebook{file="./example.ipynb"}
:::

With Options

:::notebook{file="./analysis.ipynb" cells="1-10" hideCode showCellNumbers}
This notebook shows our data analysis results
:::

Selective Cells

:::notebook{file="./demo.ipynb" cells="3,5,7-9"}
:::

🎨 Authentic Styling

The plugin provides authentic Jupyter notebook styling that matches VSCode and Jupyter Lab:

• Input prompts: Blue In [n]: indicators
• Output prompts: Orange Out[n]: indicators
• Cell borders: Subtle borders with hover effects
• Monospace fonts: System monospace fonts for code
• Color scheme: Authentic Jupyter color palette
• Responsive design: Works on all screen sizes
• Theme adaptive: Inherits your site's light/dark theme

📝 Cell Types Supported

Code Cells

• Python, JavaScript, SQL, Bash, and more
• Execution counts and outputs
• Syntax highlighting with highlight.js
• Language detection from metadata

Markdown Cells

• Full markdown support
• Proper typography
• Code blocks and syntax highlighting

Raw Cells

• Plain text display
• No processing or rendering
• Useful for data and configuration

🔧 Plugin Configuration

You can configure the plugin behavior:

import { remarkNotebookDirective } from 'notebook-mdx';

// With options
remarkPlugins: [
  remarkDirective,
  [remarkNotebookDirective, {
    baseDir: './notebooks',
    componentName: 'CustomNotebookLoader'
  }]
]

Plugin Options

• baseDir: Base directory for resolving relative notebook paths
• componentName: Custom component name for rendering (default: 'NotebookLoader')

🚀 How It Works

1. Remark Plugin: Processes :::notebook directives in your MDX
2. Automatic Loading: Reads and parses notebook files at build time
3. Component Injection: Transforms directives into React components
4. Seamless Rendering: Displays notebooks with authentic Jupyter styling

No manual component imports needed - everything works automatically through the remark plugin!

🔧 Development Notes

Current workflow: When you edit a notebook file, changes won't automatically appear in your browser. To see updates:

1. Resave the MDX file that contains the notebook directive, or
2. Make a small edit to the MDX file and save, or
3. Restart your dev server if the above doesn't work

Coming soon: Hot module reload support for notebook files is a high priority on our roadmap!

🔧 Next Steps

• Framework Integration - Complete setup guides for popular frameworks
• Advanced Usage - Learn about cell-level language detection, custom styling, and advanced features
• API Reference - Complete API documentation for the remark plugin

Get started with notebook-mdx today and bring your Jupyter notebooks to life in MDX!