Render Jupyter notebooks in MDX with authentic styling and syntax highlighting
Documentation • Demo • NPM • GitHub
- 🎨 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
npm install notebook-mdx remark-directive
# or
yarn add notebook-mdx remark-directive
# or
pnpm add notebook-mdx remark-directiveConfigure 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'],
});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
:::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)} />- Getting Started - Installation and basic usage
- Advanced Usage - Multi-language support and configuration
- API Reference - Complete component props and options
- Live Demo - Interactive examples
Perfect for data science blogs, tutorials, and educational content where you want to show Jupyter notebooks inline with your documentation.
Embed computational notebooks directly in academic papers and research documentation.
Showcase your data analysis projects with authentic notebook styling in your portfolio site.
Document data pipelines, analysis workflows, and research findings in company wikis and documentation sites.
| 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 |
|
Generic code blocks with basic syntax highlighting
|
Authentic Jupyter styling with In/Out prompts
|
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
:::# 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 buildWe welcome contributions! Please see our Contributing Guide for details.
- Jupyter Project for the amazing notebook format
- Highlight.js for syntax highlighting
- MDX for making this integration possible
MIT © Abhay Ramesh
⭐ Star this repo if notebook-mdx helped you!
Made with ❤️ by @abhay-ramesh