https://github.com/abhay-ramesh/notebook-mdx
Render Jupyter notebooks in MDX with authentic styling and syntax highlighting
https://github.com/abhay-ramesh/notebook-mdx
documentation jupyter-notebook mdx nextjs rehype remark
Last synced: 2 months ago
JSON representation
Render Jupyter notebooks in MDX with authentic styling and syntax highlighting
- Host: GitHub
- URL: https://github.com/abhay-ramesh/notebook-mdx
- Owner: abhay-ramesh
- License: mit
- Created: 2025-07-08T20:00:37.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2026-03-27T21:04:45.000Z (3 months ago)
- Last Synced: 2026-03-28T02:11:11.368Z (3 months ago)
- Topics: documentation, jupyter-notebook, mdx, nextjs, rehype, remark
- Language: TypeScript
- Homepage: https://notebook-mdx.vercel.app
- Size: 1.71 MB
- Stars: 9
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# notebook-mdx
**Render Jupyter notebooks in MDX with authentic styling and syntax highlighting**
[](https://www.npmjs.com/package/notebook-mdx)
[](https://www.npmjs.com/package/notebook-mdx)
[](https://bundlephobia.com/package/notebook-mdx)
[](https://github.com/abhay-ramesh/notebook-mdx)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
[Documentation](https://notebook-mdx.vercel.app) • [Demo](https://notebook-mdx.vercel.app/notebook-demo) • [NPM](https://www.npmjs.com/package/notebook-mdx) • [GitHub](https://github.com/abhay-ramesh/notebook-mdx)
## ✨ 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
```bash
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:
```javascript
// 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:
```mdx
# 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:
```mdx
import { NotebookLoader, NotebookStyles } from "notebook-mdx";
import notebook from "./my-notebook.ipynb";
```
## 📖 Documentation
- **[Getting Started](https://notebook-mdx.vercel.app)** - Installation and basic usage
- **[Advanced Usage](https://notebook-mdx.vercel.app/advanced)** - Multi-language support and configuration
- **[API Reference](https://notebook-mdx.vercel.app/api)** - Complete component props and options
- **[Live Demo](https://notebook-mdx.vercel.app/notebook-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
```mdx
// 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
```mdx
---
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
```mdx
---
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
```bash
# 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](CONTRIBUTING.md) for details.
- 🐛 [Report bugs](https://github.com/abhay-ramesh/notebook-mdx/issues/new?template=bug_report.md)
- 💡 [Request features](https://github.com/abhay-ramesh/notebook-mdx/issues/new?template=feature_request.md)
- 📖 [Improve docs](https://github.com/abhay-ramesh/notebook-mdx/tree/main/apps/docs)
- 🔧 [Submit PRs](https://github.com/abhay-ramesh/notebook-mdx/pulls)
## 🙏 Acknowledgments
- [Jupyter Project](https://jupyter.org/) for the amazing notebook format
- [Highlight.js](https://highlightjs.org/) for syntax highlighting
- [MDX](https://mdxjs.com/) for making this integration possible
## 📄 License
MIT © [Abhay Ramesh](https://github.com/abhay-ramesh)
---
**[⭐ Star this repo](https://github.com/abhay-ramesh/notebook-mdx) if notebook-mdx helped you!**
Made with ❤️ by [@abhay-ramesh](https://github.com/abhay-ramesh)