Notebook extension structureΒΆ

The nbextensions are stored each as a separate subdirectory of src/jupyter_contrib_nbextensions/nbextensions

Each notebook extension typically has its own directory containing:

  • thisextension/main.js: javascript implementing the nbextension
  • thisextension/main.css: optional CSS
  • thisextension/readme.md: readme file describing the nbextension in markdown format
  • thisextension/config.yaml: file describing the nbextension to the jupyter_nbextensions_configurator server extension

The file names do not need to have the shown names, they can be choosen freely. This is an example for the main.js file:

define([
    'jquery',
    'base/js/namespace',
    'base/js/utils',
    'services/config'
], function (
    $,
    IPython,
    utils,
    configmod,
) {
    "use strict";

    // define default values for config parameters
    var params = {
        my_config_value : 100
    };

    // create config object to load parameters
    var base_url = utils.get_body_data("baseUrl");
    var config = new configmod.ConfigSection('notebook', {base_url: base_url});

    // update params with any specified in the server's config file
    var update_params = function() {
        for (var key in params) {
            if (config.data.hasOwnProperty(key))
                params[key] = config.data[key];
        }
    };

    // will be called when the config parameters have been loaded
    config.loaded.then( function() {
        update_params();

    });

    function config_loaded_callback () {
        $.extend(true, params, config.data.thisextension);
    };

    // will be called when the nbextension is loaded
    var load_ipython_extension = function () {
        config.load(); // trigger loading config parameters

    };

    // return public methods
    return {
        load_jupyter_extension : load_jupyter_extension
    };
});

And for the config.yaml file:

Type: Jupyter Notebook Extension
Compatibility: 4.x
Name: thisextension
Main: main.js
Icon: icon.png
Link: README.md
Description: My super duper extension
Parameters:
- name: my_config_value
  description: A configuration parameter
  input_type: number
  min: -1
  step: 1
  default: 100

When supplying a readme.md file, please supply a main heading with the nbextension’s title, as this will be linked in the generated documentation at jupyter-contrib-nbextensions.readthedocs.io. This is a simple example for readme.md:

This extension
==============

How to use
----------
Some description here.

![Screenshot image](screenshot.png)

Internals
---------
How this extension works.