notebook-mdx

Render Jupyter notebooks in MDX with authentic styling and syntax highlighting

Documentation • Demo • NPM • GitHub

✨ Features

• 🎨 Authentic Jupyter styling - Pixel-perfect recreation of Jupyter notebook appearance
• 🖥️ Syntax highlighting - Multi-language code highlighting with Highlight.js
• 📱 Responsive design - Looks great on desktop, tablet, and mobile
• ⚡ Zero client-side dependencies - Renders at build time for optimal performance
• 🔧 Framework agnostic - Works with Next.js, Docusaurus, Fumadocs, and more
• 📦 TypeScript support - Full type safety out of the box
• 🎯 Simple API - Just import and render, no complex configuration
• 🔄 Multi-language cells - Python, R, JavaScript, SQL, and more
• 🖼️ Rich outputs - Images, HTML, JSON, and text outputs
• 📋 Copy-paste ready - Code cells with built-in copy functionality

🚀 Quick Start

Installation

npm install notebook-mdx remark-directive
# or
yarn add notebook-mdx remark-directive
# or
pnpm add notebook-mdx remark-directive

Setup

Configure the remark plugin in your MDX setup:

// next.config.js
import remarkDirective from 'remark-directive';
import { remarkNotebookDirective } from 'notebook-mdx';

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [
      remarkDirective,
      remarkNotebookDirective,
    ],
  },
});

module.exports = withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'mdx'],
});

Basic Usage

Use the notebook directive in your MDX files:

# My Data Analysis

:::notebook{file="./my-notebook.ipynb"}
This notebook shows our analysis results
:::

More content here...

:::notebook{file="./demo.ipynb" cells="1-5" showCellNumbers}
Selected cells from another notebook
:::

Alternative: Direct Component Usage

For more control, you can also use components directly:

import { NotebookLoader, NotebookStyles } from "notebook-mdx";
import notebook from "./my-notebook.ipynb";

<NotebookStyles />
<NotebookLoader notebookData={JSON.parse(notebook)} />

📖 Documentation

• Getting Started - Installation and basic usage
• Advanced Usage - Multi-language support and configuration
• API Reference - Complete component props and options
• Live Demo - Interactive examples

🎯 Use Cases

📚 Technical Documentation

Perfect for data science blogs, tutorials, and educational content where you want to show Jupyter notebooks inline with your documentation.

🔬 Research Papers

Embed computational notebooks directly in academic papers and research documentation.

📊 Data Science Portfolios

Showcase your data analysis projects with authentic notebook styling in your portfolio site.

🏢 Internal Documentation

Document data pipelines, analysis workflows, and research findings in company wikis and documentation sites.

🌟 Why notebook-mdx?

Feature	notebook-mdx	Alternatives
Authentic Styling	✅ Pixel-perfect Jupyter look	❌ Generic code blocks
Zero Runtime	✅ Renders at build time	❌ Client-side rendering
TypeScript	✅ Full type safety	❌ Limited or no types
Framework Support	✅ Works everywhere	❌ Framework-specific
Bundle Size	✅ ~15kB minzipped	❌ Often 100kB+
Maintenance	✅ Actively maintained	❌ Many are abandoned

🖼️ Screenshots

Before (Plain Markdown) Generic code blocks with basic syntax highlighting

After (notebook-mdx) Authentic Jupyter styling with In/Out prompts

🔧 Framework Examples

Next.js App Router

// app/blog/my-analysis/page.mdx
export const metadata = {
  title: "My Data Analysis",
  description: "Deep dive into user behavior data"
};

# My Data Analysis

:::notebook{file="./analysis.ipynb" showCellNumbers}
This notebook shows our user behavior analysis
:::

:::notebook{file="./additional-analysis.ipynb" cells="1-3" hideCode}
Key findings from our research
:::

Docusaurus

---
title: Machine Learning Tutorial
---

# Machine Learning Tutorial

:::notebook{file="./tutorial.ipynb" showCellNumbers showOutputs}
Complete machine learning workflow
:::

:::notebook{file="./exercises.ipynb" cells="1,3,5"}
Practice exercises
:::

Fumadocs

---
title: API Documentation
description: Complete guide to our data API
---

# API Documentation

:::notebook{file="./api-examples.ipynb" hideCode showOutputs}
Live API examples and responses
:::

:::notebook{file="./advanced-usage.ipynb" cells="1-5"}
Advanced usage patterns
:::

🏗️ Development

# Clone the repository
git clone https://github.com/abhay-ramesh/notebook-mdx.git
cd notebook-mdx

# Install dependencies
pnpm install

# Start development
pnpm dev

# Run tests
pnpm test

# Build packages
pnpm build

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

• 🐛 Report bugs
• 💡 Request features
• 📖 Improve docs
• 🔧 Submit PRs

🙏 Acknowledgments

• Jupyter Project for the amazing notebook format
• Highlight.js for syntax highlighting
• MDX for making this integration possible

📄 License

MIT © Abhay Ramesh

---

⭐ Star this repo if notebook-mdx helped you!

Made with ❤️ by @abhay-ramesh