sphinxcontrib-lightbox2¶

Sphinx extension to add lightbox2 to each figure and image added in HTML.

Read the documentation on ReadTheDocs!

Usually Sphinx themes limit their content width to a limit to improve readability. This creates a problem for large images and diagrams which might be needed in technical documentation.

Installation¶

Install the package using

pip install sphinxcontrib-lightbox2

Add sphinxcontrib.lightbox2 to the list of extensions in your conf.py:

extensions = ["sphinxcontrib.lightbox2"]

Configuration¶

Lightbox2 offers different configuration options. These options are exposed in sphinxcontrib-lightbox2 through options in the conf.py.

See the mapping of lightbox2 options to Sphinx options

Lightbox2 Option Name	Sphinx Option Name	Default Value
`alwaysShowNavOnTouchDevices`	`lightbox2_always_show_nav_on_touch_devices`	`False`
`albumLabel`	`lightbox2_album_label`	`"Image %1 of %2"`
`disableScrolling`	`lightbox2_disable_scrolling`	`False`
`fadeDuration`	`lightbox2_fade_duration`	`600`
`fitImagesInViewport`	`lightbox2_fit_images_in_viewport`	`True`
`imageFadeDuration`	`lightbox2_image_fade_duration`	`600`
`maxWidth`	`lightbox2_max_width`	`None`
`maxHeight`	`lightbox2_max_height`	`None`
`positionFromTop`	`lightbox2_position_from_top`	`50`
`resizeDuration`	`lightbox2_resize_duration`	`700`
`showImageNumberLabel`	`lightbox2_show_image_number_label`	`True`
`wrapAround`	`lightbox2_wrap_around`	`True`

Examples¶

These examples show how the lightbox2 applied to the images look. Click on any of the images to see the effect.

Figure¶

The following diagram is a normal figure included using the standard figure directive.

Image¶

Use a normal image directive to add the behavior to images.

PlantUML Diagram¶

Important

The lightbox does not work with the plantuml_output_format svg_obj. All other formats are supported.

Use the uml directive from the sphinxcontrib.plantuml extension to add the effect to PlantUML diagrams.

@startuml Example sequence chart
alice -> bob ++ : hello
bob -> bob ++ : self call
bob -> bib ++ #005500 : hello
bob -> george ** : create
return done
return rc
bob -> george !! : delete
return success
@enduml — Caption with **bold** and *italic*¶

Mermaid Diagram¶

Important

The lightbox effect is only supported if mermaid_output_format is set to png. Other formats either produce inline SVG or are handled by mermaid-js in the browser directly.

Using the mermaid_output_format png requires the mermaid-cli to be available.

Use the mermaid directive from the sphinxcontrib.mermaid extension to add the effect to Mermaid diagrams.

sequenceDiagram
participant Alice
participant Bob
Alice->John: Hello John, how are you?
loop Healthcheck
John->John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail...
John-->Alice: Great!
John->Bob: How about you?
Bob-->John: Jolly good!