Multiple Kernel Support

MkDocs-Jupyter supports notebooks written in multiple programming languages through different Jupyter kernels. This allows you to create documentation that includes examples in Python, R, Julia, Ruby, and many other languages.

Supported Kernels

While Python is the default kernel, you can use any kernel that's installed in your Jupyter environment:

• Python 3 - Default kernel for data science and general programming
• R (IRkernel) - Statistical computing and data analysis
• Julia (IJulia) - High-performance scientific computing
• Ruby (IRuby) - Web development and scripting
• JavaScript (IJavascript) - Frontend development examples
• Bash - System administration and DevOps
• SQL - Database queries and examples
• And many more...

Configuration

The MkDocs configuration already supports multiple kernels:

plugins:
  - mkdocs-jupyter:
      kernel_name: python3       # Default kernel
      execute: true             # Execute all notebooks
      allow_errors: true        # Continue even if execution fails

Individual notebooks can specify their own kernel in the notebook metadata.

Installing Additional Kernels

R Kernel (IRkernel)

# In R console
install.packages('IRkernel')
IRkernel::installspec()

Julia Kernel (IJulia)

# In Julia console
using Pkg
Pkg.add("IJulia")

Ruby Kernel (IRuby)

gem install iruby
iruby register --force

JavaScript Kernel

npm install -g ijavascript
ijsinstall

Creating Multi-Language Documentation

You can create comprehensive documentation that shows the same concept in multiple languages:

1. Algorithm Implementation - Show the same algorithm in Python, Julia, and C++
2. Data Analysis - Compare approaches in Python, R, and Julia
3. Web API Clients - Examples in Python, Ruby, JavaScript, and Go
4. System Scripts - Bash, Python, and PowerShell examples

Example Notebooks

We've created example notebooks for different kernels:

• Python Kernel Example - Data science with Python
• R Kernel Example - Statistical analysis with R
• Julia Kernel Example - Scientific computing with Julia
• Ruby Kernel Example - Scripting with Ruby

Kernel-Specific Features

Python

• Rich ecosystem of data science libraries
• Excellent visualization tools
• Machine learning frameworks
• Web development capabilities

R

• Statistical analysis functions
• Advanced plotting capabilities
• Bioinformatics packages
• Time series analysis

Julia

• High-performance computing
• Mathematical optimization
• Parallel processing
• Scientific simulations

Ruby

• Web development (Rails)
• Scripting and automation
• Metaprogramming
• DSL creation

Best Practices

1. Specify Kernel Explicitly

Always specify the kernel in your notebook metadata:

{
  "kernelspec": {
    "display_name": "Python 3",
    "language": "python",
    "name": "python3"
  }
}

2. Handle Missing Kernels Gracefully

Use allow_errors: true in your MkDocs configuration to prevent build failures if a kernel isn't available:

plugins:
  - mkdocs-jupyter:
      allow_errors: true
      execute_ignore: ["notebooks/optional/*.ipynb"]

3. Document Requirements

For each notebook, document the kernel installation requirements:

## Requirements

This notebook requires the R kernel. Install it with:
\`\`\`bash
R -e "install.packages('IRkernel'); IRkernel::installspec()"
\`\`\`

4. Use Language-Specific Features

Take advantage of each language's strengths:

• Python: Use type hints and docstrings
• R: Leverage vectorized operations
• Julia: Utilize multiple dispatch
• Ruby: Employ blocks and metaprogramming

Troubleshooting

Kernel Not Found

If a notebook fails with "kernel not found":

1. Check available kernels: jupyter kernelspec list
2. Install the missing kernel
3. Restart the MkDocs build

Execution Errors

For notebooks that may fail in CI/CD:

1. Add to execute_ignore list
2. Set allow_errors: true
3. Pre-execute notebooks and commit outputs

Performance Issues

For slow-executing notebooks:

1. Consider pre-executing and saving outputs
2. Use execute: false for specific notebooks
3. Implement caching mechanisms

Advanced Usage

Multi-Kernel Workflows

Create notebooks that demonstrate interoperability:

1. Data preparation in Python
2. Statistical analysis in R
3. Performance optimization in Julia
4. Web API in Ruby

Kernel Comparison

Create side-by-side comparisons:

# Python
def fibonacci(n):
    a, b = 0, 1
    for _ in range(n):
        a, b = b, a + b
    return a

# R
fibonacci <- function(n) {
  a <- 0
  b <- 1
  for (i in 1:n) {
    temp <- b
    b <- a + b
    a <- temp
  }
  return(a)
}

# Julia
function fibonacci(n)
    a, b = 0, 1
    for _ in 1:n
        a, b = b, a + b
    end
    return a
end

Conclusion

Multiple kernel support in MkDocs-Jupyter enables you to create rich, multi-language documentation that serves diverse audiences and use cases. Whether you're documenting a polyglot project, comparing language features, or teaching programming concepts, multiple kernels provide the flexibility you need.