Learn about multi-language support, cell-level language detection, and advanced features

Advanced Usage

Learn about advanced features including multi-language support, cell-level language detection, and customization options with the :::notebook directive.

🌐 Multi-Language Support

notebook-mdx supports multiple programming languages within a single notebook, with automatic language detection.

Language Detection Hierarchy

The language detection follows this priority order:

VSCode metadata: cell.metadata.vscode.languageId
Cell metadata: cell.metadata.languageId or cell.metadata.language
Raw cells: Always display as raw
Notebook kernel: Fallback to notebook's default language

Example Multi-Language Notebook

Here's what a multi-language notebook looks like:

:::notebook{file="./multi-language-demo.ipynb" showLanguageIndicators}
This notebook demonstrates different languages in different cells
:::

Language Indicators

With showLanguageIndicators enabled, you'll see language badges in the bottom-right corner of each cell:

Python cells: python (kernel default)
JavaScript cells: javascript (VSCode metadata)
SQL cells: sql (cell metadata)
Raw cells: raw (always raw)

🔧 Advanced Directive Options

Cell Selection

Select specific cells or ranges:

<!-- Single cell -->
:::notebook{file="./analysis.ipynb" cells="1"}
Show only the first cell
:::

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

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

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

Display Options

Control what gets displayed:

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

<!-- Show code, hide outputs -->
:::notebook{file="./code-examples.ipynb" hideCode=false showOutputs=false}
Show only the code
:::

<!-- Show cell numbers -->
:::notebook{file="./tutorial.ipynb" showCellNumbers}
Tutorial with numbered cells
:::

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

🔧 Plugin Configuration

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

Advanced Plugin Options

// With custom options
remarkPlugins: [
  remarkDirective,
  [remarkNotebookDirective, {
    baseDir: './content/notebooks',    // Base directory for notebooks
    componentName: 'CustomNotebook'    // Custom component name
  }]
]

Fumadocs Configuration

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

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

🎨 Custom Styling

CSS Custom Properties

You can customize the styling using CSS custom properties:

/* Customize notebook container */
.notebook-container {
  --notebook-border-color: #e1e5e9;
  --notebook-border-radius: 8px;
  --notebook-background: #ffffff;
  --notebook-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
  
  border: 1px solid var(--notebook-border-color);
  border-radius: var(--notebook-border-radius);
  background: var(--notebook-background);
  box-shadow: var(--notebook-shadow);
}

/* Customize cell styling */
.notebook-cell {
  --cell-border-color: #f0f0f0;
  --cell-background: #fafafa;
  --cell-padding: 1rem;
  
  border-bottom: 1px solid var(--cell-border-color);
  background: var(--cell-background);
  padding: var(--cell-padding);
}

/* Customize prompt colors */
.notebook-prompt {
  --prompt-input-color: #0969da;
  --prompt-output-color: #cf222e;
  --prompt-font-weight: 600;
  
  font-weight: var(--prompt-font-weight);
}

.notebook-prompt.input {
  color: var(--prompt-input-color);
}

.notebook-prompt.output {
  color: var(--prompt-output-color);
}

Theme Integration

Light/Dark Theme Support

/* Light theme */
[data-theme="light"] .notebook-container {
  --notebook-background: #ffffff;
  --notebook-border-color: #e1e5e9;
  --cell-background: #f8f9fa;
  --text-color: #24292f;
}

/* Dark theme */
[data-theme="dark"] .notebook-container {
  --notebook-background: #0d1117;
  --notebook-border-color: #30363d;
  --cell-background: #161b22;
  --text-color: #c9d1d9;
}

Custom Theme Classes

You can create custom themes by targeting the notebook containers with CSS:

/* Custom purple theme */
.my-page .notebook-container {
  --notebook-background: #f8f4ff;
  --notebook-border-color: #8b5cf6;
  --cell-background: #faf5ff;
  --prompt-input-color: #7c3aed;
  --prompt-output-color: #c084fc;
}

<!-- Notebook will inherit the theme from the page -->
:::notebook{file="./demo.ipynb"}
Purple themed notebook
:::

🚀 Interactive Features

Dynamic Loading

Load notebooks dynamically based on conditions:

<!-- Basic example -->
:::notebook{file="./basic.ipynb"}
Basic example
:::

<!-- Advanced example -->
:::notebook{file="./advanced.ipynb" cells="5-10"}
Advanced concepts
:::

🔍 Performance Optimization

Large Notebook Handling

For large notebooks, use cell selection to improve performance:

<!-- Show only key cells -->
:::notebook{file="./large-analysis.ipynb" cells="1,5,10,15"}
Key results from large analysis
:::

<!-- Show summary cells -->
:::notebook{file="./large-analysis.ipynb" cells="1-3,25-30"}
Introduction and conclusions
:::

Lazy Loading

Notebooks are loaded and parsed at build time, ensuring fast runtime performance.

🎯 Best Practices

1. Organize Notebooks

content/
├── notebooks/
│   ├── basics/
│   │   ├── intro.ipynb
│   │   └── setup.ipynb
│   ├── advanced/
│   │   ├── analysis.ipynb
│   │   └── visualization.ipynb
│   └── examples/
│       └── demo.ipynb

2. Use Descriptive Captions

:::notebook{file="./analysis.ipynb" cells="1-5" showCellNumbers}
This analysis shows customer behavior patterns using Python pandas.
The first 5 cells demonstrate data loading and initial exploration.
:::

3. Selective Display

<!-- Show code for learning -->
:::notebook{file="./tutorial.ipynb" showCellNumbers}
Learn the implementation details
:::

<!-- Show results for reports -->
:::notebook{file="./results.ipynb" hideCode}
View the analysis results
:::

4. Consistent Display Options

<!-- Use consistent display options -->
:::notebook{file="./demo1.ipynb" showCellNumbers}
First tutorial
:::

:::notebook{file="./demo2.ipynb" showCellNumbers}
Second tutorial
:::

🔧 Troubleshooting

Common Issues

File not found: Check the notebook path relative to your MDX file
Missing language indicators: Ensure showLanguageIndicators is enabled
Styling issues: Check CSS custom properties and theme integration
Performance issues: Use cell selection for large notebooks

Debug Tips

<!-- Test with minimal options -->
:::notebook{file="./test.ipynb"}
:::

<!-- Add options incrementally -->
:::notebook{file="./test.ipynb" showCellNumbers}
:::

This advanced usage guide should help you leverage the full power of notebook-mdx with the directive-based approach!

Advanced Usage

On this page