API Reference

Complete reference documentation for the remarkNotebookDirective remark plugin and its TypeScript interfaces.

🔌 Remark Plugin

remarkNotebookDirective

The main remark plugin that processes :::notebook directives in MDX files.

import { remarkNotebookDirective } from 'notebook-mdx';
import type { NotebookDirectiveOptions } from 'notebook-mdx';

// Basic usage
remarkPlugins: [
  remarkDirective,
  remarkNotebookDirective,
]

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

Plugin Options

interface NotebookDirectiveOptions {
  baseDir?: string;
  componentName?: string;
}

Option	Type	Default	Description
`baseDir`	`string`	`process.cwd()`	Base directory for resolving relative notebook paths
`componentName`	`string`	`'NotebookLoader'`	Custom component name for rendering

📝 Directive Syntax

The plugin processes :::notebook directives with the following syntax:

:::notebook{file="./path/to/notebook.ipynb" cells="1-5" showCellNumbers}
Optional caption or description
:::

Directive Options

Option	Type	Default	Description
`file`	`string`	Required	Path to the notebook file (relative to baseDir)
`cells`	`string`	`undefined`	Specific cells to show (e.g., "1-5", "1,3,5")
`hideCode`	`boolean`	`false`	Hide code cells
`showOutputs`	`boolean`	`true`	Show cell outputs
`showCellNumbers`	`boolean`	`false`	Show cell numbers (In[n]/Out[n])
`showLanguageIndicators`	`boolean`	`false`	Show language indicators

Cell Selection

The cells option supports flexible cell selection:

<!-- Single cell -->
:::notebook{file="./demo.ipynb" cells="1"}
:::

<!-- Range of cells -->
:::notebook{file="./demo.ipynb" cells="1-5"}
:::

<!-- Multiple specific cells -->
:::notebook{file="./demo.ipynb" cells="1,3,5"}
:::

<!-- Mixed ranges and specific cells -->
:::notebook{file="./demo.ipynb" cells="1-3,5,7-9"}
:::

🏗️ Generated Output

The plugin transforms notebook directives into React components:

<!-- Input -->
:::notebook{file="./example.ipynb" showCellNumbers}
Data analysis results
:::

<!-- Output (generated) -->
<NotebookLoader
  notebookData={{...}}
  showCellNumbers={true}
  children="Data analysis results"
/>

🎨 Styling

The plugin injects CSS styles automatically. No manual style imports needed.

Custom Styling

You can customize the appearance with CSS:

/* Target the notebook container */
.notebook-container {
  border: 1px solid #e1e5e9;
  border-radius: 8px;
  overflow: hidden;
}

/* Style code cells */
.notebook-cell-code {
  background-color: #f8f9fa;
}

/* Style markdown cells */
.notebook-cell-markdown {
  padding: 1rem;
}

/* Custom prompt styling */
.notebook-prompt-input {
  color: #0969da;
  font-weight: 600;
}

.notebook-prompt-output {
  color: #cf222e;
  font-weight: 600;
}

📋 TypeScript Types

Essential types for TypeScript development:

import type { 
  NotebookDirectiveOptions,
  NotebookData,
  NotebookCell,
  NotebookMetadata,
  NotebookOutput
} from 'notebook-mdx';

NotebookData

interface NotebookData {
  cells: NotebookCell[];
  metadata: NotebookMetadata;
  nbformat: number;
  nbformat_minor: number;
}

NotebookCell

interface NotebookCell {
  cell_type: 'code' | 'markdown' | 'raw';
  source: string | string[];
  metadata?: CellMetadata;
  
  // Code cells only
  execution_count?: number | null;
  outputs?: NotebookOutput[];
  
  // Markdown cells only
  attachments?: Record<string, any>;
}

NotebookMetadata

interface NotebookMetadata {
  kernelspec?: {
    display_name: string;
    language: string;
    name: string;
  };
  language_info?: {
    name: string;
    version?: string;
    mimetype?: string;
    file_extension?: string;
  };
  [key: string]: any;
}

NotebookOutput

interface NotebookOutput {
  output_type: 'stream' | 'display_data' | 'execute_result' | 'error';
  
  // Stream output
  name?: string;
  text?: string | string[];
  
  // Display/execute result
  data?: Record<string, any>;
  metadata?: Record<string, any>;
  execution_count?: number;
  
  // Error output
  ename?: string;
  evalue?: string;
  traceback?: string[];
}

🔧 Configuration Examples

Basic 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'],
});

With Custom Options

// With custom base directory
remarkPlugins: [
  remarkDirective,
  [remarkNotebookDirective, {
    baseDir: './content/notebooks',
    componentName: 'CustomNotebookRenderer'
  }]
]

Fumadocs Setup

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

export default defineConfig({
  mdxOptions: {
    remarkPlugins: [
      remarkDirective,
      remarkNotebookDirective,
    ],
  },
});

🚀 Advanced Usage

Dynamic Notebook Loading

<!-- Load different notebooks based on conditions -->
:::notebook{file="./basic.ipynb" cells="1-3"}
Basic example
:::

:::notebook{file="./advanced.ipynb" cells="5-10" hideCode}
Advanced results only
:::

Display Options

<!-- Show cell numbers -->
:::notebook{file="./demo.ipynb" showCellNumbers}
:::

<!-- Hide code, show outputs only -->
:::notebook{file="./results.ipynb" hideCode}
:::

<!-- Show language indicators -->
:::notebook{file="./multi-lang.ipynb" showLanguageIndicators}
:::

This API provides a clean, plugin-based approach to notebook rendering in MDX with zero manual configuration required!

API Reference

On this page