2 Extensions

aka majordome.magic

On top of your notebook, simply load the extension:

%load_ext majordome.magic

For JupyterLab 4, a dedicated frontend extension is now available in this repository at jupyterlab/majordome-mdmagic.

cd jupyterlab/majordome-mdmagic
npm install
npm run build
jupyter labextension link .

After this, start JupyterLab as usual and the extension will switch %%md code cells to Markdown highlighting (or LaTeX for pure $$...$$ display-math bodies).

2.1 Skipping execution

SkipperMagic

SkipperMagic():

An extension for skipping the execution of code cells.

The module provides a simple extension for skipping the execution of code cells in a notebook. It does that and only that. The goal is to control notebook execution from the environment, which is useful when running notebooks with long-running cells, as numerical simulations.

%skipper_verbosity 1

Setting skipper verbosity to 1

Here we will use sleep to emulate a long-running cell, and we will control its execution with an environment variable. Generally speaking, the goal is to export environment variables in the terminal before running the notebook, but for demonstration purposes, we will set it in the notebook itself.

from time import sleep
import os

The following (case insensitive) options are accepted by the %%skipper magic command. Please, notice that the truthy values mean skip this cell (as the extension name implies, but even myself can be confused by the double negative here).

{'true': True, '1': True, 'yes': True, 'false': False, '0': False, 'no': False}

Below we set the environment variable SOLVE_LONNNNG to true, which means that the cell will be skipped. You can change it to false to execute the cell, or even set it to any other value, as long as it is in the lookup table.

os.environ["SOLVE_LONNNNG"] = "true"

did_you_skip_it = True

If everything is file, the following cell will be skipped:

%%skipper SOLVE_LONNNNG
sleep(100)
did_you_skip_it = False

Skipping cell: SOLVE_LONNNNG=True

And here we check if it was actually skipped:

print("Did you skip it?", did_you_skip_it)

Did you skip it? True

You can also avoid the Skipping cell message by setting the verbosity to 0:

%skipper_verbosity 0

%%skipper SOLVE_LONNNNG
sleep(100)
did_you_skip_it = False

2.2 Markdown and LaTeX interpolation

MdMagic

MdMagic():

An extension for interpolating code in Markdown.

Cell magic extension to interpolate Markdown and LaTeX. It must be used from code cells and the content is rendered as Markdown. As such, it is expected to be used only when required, as without some frontend tweaks you will have undesirable syntax highlighting in the cell, as it is not interpreted as text. Nonetheless, this proves very useful for complex reporting with dynamic values.

Variables are interpolated from the IPython user namespace using Python format placeholders, e.g. {variable}.
If a variable is not found or evaluation fails, the original placeholder is left unchanged in the output, e.g. {variable}. For details, check eval_placeholder method.
Curly braces inside LaTeX math blocks ( $...$ or $$...$$) are automatically escaped before interpolation so expressions such as $x_{i}$ render correctly.
You can override the interpretation of curly braces inside LaTex math blocks by providing a format spec, e.g. {variable:.2f}.

Declare some values in the user namespace:

variable = "hello"
some_value = 12.2

Below we have a Markdown cell with some variables and LaTeX expressions. The variables will be replaced by their values, and the LaTeX will be rendered correctly.

%%md
I have this string with a variable: {variable}.

There is also some latex: $\int_a^b f(x) \; dx$.

- Some formatter value {some_value:.2f}

- Some block math:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

I have this string with a variable: hello.

There is also some latex: $\int_a^b f(x) \; dx$.

Some formatter value 12.20
Some block math:

\[ \int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2} \]

About Quarto rendering

Please notice that when working in VSCode Jupyter extension, the following currently fails, i.e. it does not recognize the %%md magic command as it is not on the top of the cell; if you change the order, the Quarto annotation will be interpreted as markdown. For properly rendering Quarto documents, consider adding a global configuration for the echo option set to false and explicitly set it to true in the cells where you want to see the code. This is a known issue that will (maybe) be fixed in the future, but for now, it is a good workaround (that actually enforces a good practice of hiding code cells in the final document, which is what you usually want when writing reports).

#| echo: false
%%md

The following is also possible in math blocks:

%%md

$$
F(x) = {some_value:.2f} \cdot x^2
$$

But there is no way to use the plain `some_value` without a format specifier, as it would be indistinguishable from a regular LaTeX expression.

$$
F(x) = {some_value} \cdot x^2
$$

\[ F(x) = 12.20 \cdot x^2 \]

But there is no way to use the plain some_value without a format specifier, as it would be indistinguishable from a regular LaTeX expression.

\[ F(x) = {some_value} \cdot x^2 \]

SymPy expressions are also supported, and they will be rendered as LaTeX. In general rendering is done by displaying some expression as provided below:

import sympy as sp

x = sp.symbols("x")
f_x = some_value * x**2
f_x

$\displaystyle 12.2 x^{2}$

With help of the extension we can also render it in markdown:

Now we can also talk about the function we just defined: $12.2 x^{2}$! If you need to inject the expression inside a math block, you can do so by calling sp.latex and using the string formatter: $f=12.2 x^{2}$. It should also work with block math:

\[ f = 12.2 x^{2} \]