Control the page layout

Warning

Many of the features on this page are experimental and may change at any time.

There are a few ways to control the layout of a page with Jupyter Book. Many of these ideas take inspiration from the Edward Tufte layout CSS guide.

Let’s begin with a sample plot. You can click the toggle button to the right to see the code that generated it.

def make_fig(figsize):
    from matplotlib import rcParams, cycler
    import matplotlib.pyplot as plt
    import numpy as np
    plt.ion()

    # Fixing random state for reproducibility
    np.random.seed(19680801)

    N = 10
    data = [np.logspace(0, 1, 100) + .2 * np.random.randn(100) + ii for ii in range(N)]
    data = np.array(data).T
    cmap = plt.cm.coolwarm
    rcParams['axes.prop_cycle'] = cycler(color=cmap(np.linspace(0, 1, N)))


    from matplotlib.lines import Line2D
    custom_lines = [Line2D([0], [0], color=cmap(0.), lw=4),
                    Line2D([0], [0], color=cmap(.5), lw=4),
                    Line2D([0], [0], color=cmap(1.), lw=4)]

    fig, ax = plt.subplots(figsize=figsize)
    lines = ax.plot(data)
    ax.legend(custom_lines, ['Cold', 'Medium', 'Hot'])
make_fig(figsize=(10, 5))
../_images/layout_1_0.png

Scrolling cell outputs

The traditional Jupyter Notebook interface allows you to toggle output scrolling for your cells. This allows you to visualize part of a long output without it taking up the entire page.

You can trigger this behavior in Jupyter Book by adding the following tag to a cell’s metadata:

{
    "tags": [
        "output_scroll",
    ]
}

For example, the following cell has a long output, but will be scrollable in the book:

for ii in range(40):
    print(f"this is output line {ii}")
this is output line 0
this is output line 1
this is output line 2
this is output line 3
this is output line 4
this is output line 5
this is output line 6
this is output line 7
this is output line 8
this is output line 9
this is output line 10
this is output line 11
this is output line 12
this is output line 13
this is output line 14
this is output line 15
this is output line 16
this is output line 17
this is output line 18
this is output line 19
this is output line 20
this is output line 21
this is output line 22
this is output line 23
this is output line 24
this is output line 25
this is output line 26
this is output line 27
this is output line 28
this is output line 29
this is output line 30
this is output line 31
this is output line 32
this is output line 33
this is output line 34
this is output line 35
this is output line 36
this is output line 37
this is output line 38
this is output line 39

Full-width content

Sometimes, you’d like to use all of the horizontal space available to you. This allows you to highlight particular ideas, visualizations, etc.

Full-width code cells

You can specify that a code cell’s inputs and/or outputs should take up all of the horizontal space (including the margin to the right) using the following cell metadata tag:

{
    "tags": [
        "full-width",
    ]
}

See also

For tips on how to add cell metadata to your notebooks, see How should I add cell tags and metadata to my notebooks?.

For example, let’s take a look at the figure in the margin above in a cell with full-width set. We’ll tell Matplotlib to make it a bit wider so we can take advantage of the extra space!

make_fig(figsize=(20, 5))
../_images/layout_8_0.png

Full-width markdown content

If you’d like to make your markdown content full-width, you cannot do so via cell tags. Instead, you have a few options:

  1. Use the {div} directive with a full-width class.. Any content with a full-width class will take up the full width of the screen. For example, the following code:

    ````{div} full-width
    ```{note}
    Here's a note that will take the full width
    ```
    ````
    

    results in:

    Note

    Here’s a note that will take the full width

    For more information on <div> blocks, see Custom <div> blocks.

  2. Add a full-width class to directives that support classes. Many directives allow you to directly add a CSS class to them.

    For example, the {note} directive above allows for this:

    ```{note}
    :class: full-width
    Here's a note that will take the full width
    ```
    

    results in:

    Note

    Here’s a note that will take the full width

    Check the documentation of the directive to see if it supports adding your own classes, or use the {div} directive as described above.

Mixing margins and full-width content

Be careful when mixing margins and full-width content. Sometimes these can conflict with one another in visual space. You should use them relatively sparingly in order for them to have their full effect of highlighting information.