Sphinx Sticky Margin

sphinx-sticky-margin is a Sphinx extension that adds a sticky margin copy for images, figures and other elements marked using the class sticky-margin.

When the original element scrolls above the header, a duplicate appears in the right margin (on wide screens). When the original element comes back into view, the margin copy is hidden.

Installation

pip install sphinx-sticky-margin

Enable Extension

In conf.py:

extensions = [
    "sphinx_sticky_margin",
]

For Jupyter Book (_config.yml):

sphinx:
  extra_extensions:
    - sphinx_sticky_margin

Usage

Enabling Sticky Margin Behavior

Add the option :figclass: sticky-margin to a figure directive that should get a sticky margin clone. (For backward compatibility, :class: sticky-margin also works for figure directives.)

Add the option :class: sticky-margin to a directive that generates an HTML <div> element that should get a sticky margin clone.

Add the option :class: sticky-margin to a image directive that should get a sticky margin clone.

The sticky margin elements will appear when the original element scrolls out of view, and will disappear when the original element comes back into view.

In case of multiple (active) sticky margin elements, all will be shown in the margin.

Disabling Sticky Margin Behavior

Insert a hide-sticky-margin directive to insert a marker after which to fade out the last sticky elements during scrolling.

If a hide marker scrolls out of view at the top when scrolling down, all sticky elements defined before that marker will be hidden.

When scrolling back up, the sticky margin elements above a hide marker (but after any previous hide marker) will reappear when that hide marker scrolls back below the header.

Sticky Margin Behavior

By default the sticky margin element will appear when the original element is fully scrolled out of view, and will disappear when the original element is partially back in view.

In partial mode, the sticky margin element will appear when the original element is partially scrolled out of view, and will disappear when the original element is fully back in view.

To set the sticky margin trigger mode, add the following to conf.py:

sticky_margin["trigger"] = "partial"  # or "full"

Or for Jupyter Book (_config.yml):

sphinx:
  config:
    sticky_margin:
      trigger: partial  # or full

If any value other than partial or full is set, the extension will fall back to the default full mode with a warning.

The order of the elements in the margin is determined by the order in which they are rendered and the trigger works on the actual rendered position of the original element. For full trigger mode, the sort order is:

1. bottom (smallest first)
2. top (smallest first)
3. left (smallest first)
4. height (smallest first)
5. width (smallest first)
6. DOM order (fallback)

For partial trigger mode, the sort order is:

1. top (smallest first)
2. bottom (smallest first)
3. left (smallest first)
4. height (smallest first)
5. width (smallest first)
6. DOM order (fallback)

[!NOTE] The combination of :class: sticky-margin, dropdown is not supported, as the dropdown behavior conflicts with the sticky margin behavior. If both classes are present, the sticky-margin class will be removed and a warning will be issued in the console.

MyST Example

```{figure} path/to/image.png
:figclass: sticky-margin

Figure caption.
```

reStructuredText Example

.. figure:: path/to/image.png
   :figclass: sticky-margin

   Figure caption.

Hide Marker (MyST)

```{hide-sticky-margin}
```

Images

```{image} path/to/image.png
:class: sticky-margin
```

Directives with :class: sticky-margin

```{admonition} This is a sticky margin admonition
:class: sticky-margin

This content will appear in the sticky margin when the original element scrolls out of view.
```

When the marker scrolls above the header, the previous sticky margin elements are hidden with a fade-out.

Notes

• The sticky margin display is active from 1200px viewport width and up.
• The extension injects sticky-margin.css and sticky-margin.js.
• The extension removes explicit line endings (<br>, double space in markdown) from figure captions to prevent layout issues in the margin.

MathJax and Lazy Loading

MathJax lazy loading is not compatible with this extension. The sticky margin works by cloning the source element. If MathJax has not yet rendered math before cloning (which happens with lazy loading when the element scrolls off-screen before the lazy observer fires), the clone will contain empty placeholders instead of rendered math.

Jupyter Book with JupyterBook-Patches

If you are using JupyterBook-Patches, lazy loading can also be disabled in one of two ways:

• Disable the mathjax patch entirely (note: this also disables the Firefox MathJax fix).
• Add ui/nonlazy to config.mathjax3_config['loader']['load'] in your config file:

sphinx:
  config:
    mathjax3_config:
      loader:
        load:
          - "ui/nonlazy"

[!NOTE] ui/nonlazy is not a MathJax-defined value. It is introduced by JupyterBook-Patches specifically to allow disabling lazy loading.