ThebeLab: turning static HTML pages into live documents
Have a static HTML page with code snippets? Your readers can edit and execute them right there. All it takes is:
- A brief header in the HTML page
- The ThebeLab javascript library (which can be fetched from the web)
- A computing backend (typically binder)
ThebeLab is a based on the Jupyter technology, and thus supports a wealth of programming languages. The original implementation, called Thebe was a fork of the Jupyter code base. ThebeLab is a reimplementation of Thebe as a thin layer on top of JupyterLab, making it more sustainable.
See the ThebeLab Documentation for more information.
See the examples directory, and browse the live output for inspiration. See also this blog post.
How ThebeLab works
Starting ThebeLab involves the following steps:
- Loading the thebelab javascript, typically from a CDN;
- Fetching the ThebeLab configuration from the page header;
- Bootstrapping ThebeLab:
- Re rendering the code cells to make them live cells. Optionally, the rendering can handle cells that contain a mixture of inputs and ouputs distinguished by prompts (see the stripPrompts option);
- (optional) Requesting a notebook server from Binder;
- (optional) Requesting a Jupyter kernel from the Jupyter server.
Bootstrap Thebelab by calling thebelab.bootstrap()
. If bootstrap: true
is
in the Thebelab configuration (see below), this will be triggered automatically
upon page load.
Configuring ThebeLab
For complete information about configuring ThebeLab, see the ThebeLab documentation.
You can configure thebelab with a script tag.
The script should have type=text/x-thebe-config
with a javascript object containing configuration options.
<script type="text/x-thebe-config">
{
binderOptions: {
repo: "minrk/ligo-binder",
ref: "master",
}
}
</script>
A full config script with defaults:
{
// Whether thebelab should automatically trigger the bootstrap upon page load
// if set to false, the page should contain some additional javascript
// responsible for triggering the javascript when desired (e.g. connected to a button click).
bootstrap: false,
// arbitrary pre-render function called as part of bootstrap
preRenderHook: false,
// Whether to request the kernel immediately when thebelab is bootstrapped
// instead of on executing code for the first time
requestKernel: false,
// Whether thebelab should look for predefined output of cells before execution
// If this option is enabled and the next div after the cell has the attribute
// data-output=true (default), then the content of this div is rendered as output
predefinedOutput: false,
// The selector for identifying whether an element should be treated as output
outputSelector: '[data-output]'
// Options for requesting a notebook server from mybinder.org
binderOptions: {
repo: "minrk/ligo-binder",
ref: "master",
binderUrl: "https://mybinder.org",
// select repository source (optional). Supports Github(default), Gitlab, and Git
repoProvider: "github",
},
// Options for requesting a kernel from the notebook server
kernelOptions: {
name: "python3",
// notebook server configuration; not needed with binder
// serverSettings: {
// "baseUrl": "http://127.0.0.1:8888",
// "token": "test-secret"
// }
},
// Selector for identifying which elements on the page should
// be made interactive
selector: "[data-executable]",
// Optional prompt handling during the rendering phase
// Either false or a dictionary as in the example below
stripPrompts: false,
// stripPrompts: {
// inPrompt: 'sage: ',
// continuationPrompt: '....: ',
// // only apply the prompt stripping to cells matching this selector (optional)
// selector: '.sage-input',
// },
// URL from which to load mathjax
// set to `false` to disable mathjax
mathjaxUrl: "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js",
// mathjax configuration string
mathjaxConfig: "TeX-AMS_CHTML-full,Safe",
// Additional options to pass to CodeMirror instances
codeMirrorConfig: {},
}
Acknowledgements
thebelab
was developed as a part of OpenDreamKit – Horizon 2020 European Research Infrastructure project (676541).