From 51ec6f21184646fe3d4184afa0c0219618f4d91e Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Tue, 23 Dec 2025 00:00:36 +0100 Subject: [PATCH 1/6] Document image zoom and lightbox features Add comprehensive documentation for the new image zoom/lightbox feature available in the TYPO3 documentation theme. Extension authors can now use CSS classes to enable different zoom modes on figures and images. Coverage includes: - Five zoom modes: lightbox, gallery, inline, lens, and css-only - Practical RST examples for each mode - Accessibility features (keyboard navigation, ARIA, screen readers) - Best practices and use case guidance - JavaScript-free fallback option This enables extension authors to enhance image viewing in their documentation without requiring custom JavaScript or external plugins. --- .../ReStructuredText/Graphics/Images.rst | 156 ++++++++++++++++++ 1 file changed, 156 insertions(+) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index 53a2a3c7..221fec01 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -83,3 +83,159 @@ Example 2: Image with caption and fixed width :width: 100px This is the image caption + +.. _image-zoom: + +Image zoom and lightbox features +================================= + +The TYPO3 documentation theme provides built-in image zoom and lightbox +features to enhance the viewing experience for images and figures. These +features allow readers to view images in greater detail without leaving +the documentation page. + +Available zoom modes +-------------------- + +The zoom functionality is controlled by adding a CSS class to your figure +or image directive. The following zoom modes are available: + +.. rst-class:: dl-parameters + +:class:`zoom-lightbox` (default) + Click to open the image in a full-screen overlay dialog. The lightbox + provides a dark backdrop and centers the image. Click outside the image + or press ESC to close. + + **Use case**: Screenshots, diagrams, and any image that benefits from + full-screen viewing. + +:class:`zoom-gallery` + Click to open the image in a gallery viewer with mouse wheel zoom + capabilities and navigation controls. Ideal for multiple related images. + + **Use case**: Series of screenshots, step-by-step tutorials, or image + galleries. + +:class:`zoom-inline` + Enables scroll wheel zoom directly on the image without opening an + overlay. The image zooms in place within the documentation. + + **Use case**: Detailed diagrams or technical drawings that need frequent + zoom inspection. + +:class:`zoom-lens` + A magnifier lens follows the cursor when hovering over the image, + showing a zoomed view of the area under the cursor. + + **Use case**: High-resolution images with fine details, such as UI + mockups or detailed screenshots. + +:class:`zoom-css-only` + A lightweight, JavaScript-free zoom that enlarges the image on hover + using only CSS. Provides basic zoom functionality without requiring + JavaScript. + + **Use case**: Simple zoom needs, or when JavaScript-free fallback is + required. + +Usage examples +-------------- + +Example 3: Lightbox zoom (default) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: /_Images/a4.jpg + :alt: Example screenshot + :class: zoom-lightbox + + Click to open in lightbox. This is the recommended mode for most images. + +.. code-block:: rst + :linenos: + + .. figure:: /_Images/a4.jpg + :alt: Example screenshot + :class: zoom-lightbox + + Click to open in lightbox. + +Example 4: Gallery mode with zoom +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + :linenos: + + .. figure:: /_Images/screenshot.png + :alt: Configuration screen + :class: zoom-gallery + :width: 600px + + Opens in gallery mode with zoom controls and navigation. + +Example 5: Inline scroll-wheel zoom +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + :linenos: + + .. figure:: /_Images/diagram.png + :alt: Architecture diagram + :class: zoom-inline + + Use scroll wheel to zoom in/out directly on this image. + +Example 6: Magnifier lens +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + :linenos: + + .. figure:: /_Images/detailed-ui.png + :alt: User interface mockup + :class: zoom-lens + + Hover over the image to see a magnified view. + +Accessibility considerations +----------------------------- + +All zoom modes are designed with accessibility in mind: + +Keyboard navigation +~~~~~~~~~~~~~~~~~~~ + +* **Lightbox and Gallery modes**: Full keyboard support + + * :kbd:`Tab` - Navigate between controls + * :kbd:`Enter` or :kbd:`Space` - Open lightbox/gallery + * :kbd:`ESC` - Close lightbox/gallery + * :kbd:`Arrow keys` - Navigate between images (gallery mode) + * :kbd:`+` / :kbd:`-` - Zoom in/out (gallery mode) + +* **Inline and Lens modes**: Mouse-based interaction, keyboard users can + open the full image in a new tab if needed + +Screen reader support +~~~~~~~~~~~~~~~~~~~~~~ + +All zoom modes maintain proper ARIA attributes and provide descriptive +labels for assistive technologies. Always use the `:alt:` parameter to +provide descriptive alternative text for images. + +JavaScript-free fallback +~~~~~~~~~~~~~~~~~~~~~~~~ + +The `zoom-css-only` mode provides a lightweight alternative that works +without JavaScript, ensuring accessibility for users with JavaScript +disabled or in restricted environments. + +Best practices +-------------- + +* Always include descriptive `:alt:` text for accessibility +* Use `zoom-lightbox` as the default for most images +* Consider `zoom-gallery` for related images that tell a story +* Use `zoom-inline` for technical diagrams that need frequent inspection +* Specify image width with `:width:` to prevent layout shifts +* Test zoom functionality with keyboard navigation From 000da30d36c61d310f591bdbe78d99e71e1e6092 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Tue, 23 Dec 2025 00:23:50 +0100 Subject: [PATCH 2/6] Fix keyboard navigation docs for Inline and Lens modes - Inline zoom has full keyboard support: Tab, +/-, arrows, ESC/0 - Lens mode has keyboard activation: Tab, Enter/Space, arrows, ESC --- .../ReStructuredText/Graphics/Images.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index 221fec01..ace18eb3 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -213,8 +213,19 @@ Keyboard navigation * :kbd:`Arrow keys` - Navigate between images (gallery mode) * :kbd:`+` / :kbd:`-` - Zoom in/out (gallery mode) -* **Inline and Lens modes**: Mouse-based interaction, keyboard users can - open the full image in a new tab if needed +* **Inline zoom mode**: Full keyboard support + + * :kbd:`Tab` - Focus the image + * :kbd:`+` / :kbd:`-` - Zoom in/out + * :kbd:`Arrow keys` - Pan when zoomed + * :kbd:`ESC` or :kbd:`0` - Reset zoom + +* **Lens mode**: Keyboard activation supported + + * :kbd:`Tab` - Focus the image + * :kbd:`Enter` or :kbd:`Space` - Toggle lens on/off + * :kbd:`Arrow keys` - Move lens position + * :kbd:`ESC` - Deactivate lens Screen reader support ~~~~~~~~~~~~~~~~~~~~~~ From fd68e5f38b3f762ddf40ca71bb80e96c761f7676 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sat, 27 Dec 2025 19:34:32 +0100 Subject: [PATCH 3/6] docs: update zoom syntax to use :zoom: option instead of class --- .../ReStructuredText/Graphics/Images.rst | 132 +++++++++++------- 1 file changed, 80 insertions(+), 52 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index ace18eb3..41fb9ceb 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -97,91 +97,109 @@ the documentation page. Available zoom modes -------------------- -The zoom functionality is controlled by adding a CSS class to your figure -or image directive. The following zoom modes are available: +The zoom functionality is controlled by the `:zoom:` option on figure +and image directives. The following zoom modes are available: .. rst-class:: dl-parameters -:class:`zoom-lightbox` (default) +`lightbox` Click to open the image in a full-screen overlay dialog. The lightbox provides a dark backdrop and centers the image. Click outside the image - or press ESC to close. + or press Escape to close. A zoom indicator icon appears on the image. **Use case**: Screenshots, diagrams, and any image that benefits from - full-screen viewing. + full-screen viewing. This is the recommended mode for most images. -:class:`zoom-gallery` +`gallery` Click to open the image in a gallery viewer with mouse wheel zoom - capabilities and navigation controls. Ideal for multiple related images. + and navigation between grouped images. Use the `:gallery:` option to + group related images together. **Use case**: Series of screenshots, step-by-step tutorials, or image - galleries. + collections that should be navigable together. -:class:`zoom-inline` +`inline` Enables scroll wheel zoom directly on the image without opening an - overlay. The image zooms in place within the documentation. + overlay. When zoomed, drag to pan. Double-click or press Escape to reset. **Use case**: Detailed diagrams or technical drawings that need frequent - zoom inspection. + zoom inspection without leaving context. -:class:`zoom-lens` +`lens` A magnifier lens follows the cursor when hovering over the image, - showing a zoomed view of the area under the cursor. + showing a zoomed view. A result panel appears beside the image with + the magnified area. **Use case**: High-resolution images with fine details, such as UI mockups or detailed screenshots. -:class:`zoom-css-only` - A lightweight, JavaScript-free zoom that enlarges the image on hover - using only CSS. Provides basic zoom functionality without requiring - JavaScript. +Directive options +----------------- - **Use case**: Simple zoom needs, or when JavaScript-free fallback is - required. +The following options are available for the figure and image directives: + +.. rst-class:: dl-parameters + +`:zoom:` + The zoom mode to use. One of: `lightbox`, `gallery`, `inline`, `lens`. + +`:gallery:` + Group name for gallery mode. Images with the same gallery name can be + navigated together. Only used with `:zoom: gallery`. + +`:zoom-indicator:` + Whether to show the zoom indicator icon. Set to `false` to hide it. + Default is `true` (shown). Usage examples -------------- -Example 3: Lightbox zoom (default) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example 3: Lightbox zoom +~~~~~~~~~~~~~~~~~~~~~~~~~ .. figure:: /_Images/a4.jpg :alt: Example screenshot - :class: zoom-lightbox + :zoom: lightbox + :class: with-border with-shadow Click to open in lightbox. This is the recommended mode for most images. .. code-block:: rst - :linenos: .. figure:: /_Images/a4.jpg :alt: Example screenshot - :class: zoom-lightbox + :zoom: lightbox + :class: with-border with-shadow Click to open in lightbox. -Example 4: Gallery mode with zoom -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Example 4: Gallery mode with grouped images +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: rst - :linenos: - .. figure:: /_Images/screenshot.png - :alt: Configuration screen - :class: zoom-gallery - :width: 600px + .. figure:: /_Images/step1.png + :alt: Step 1 + :zoom: gallery + :gallery: tutorial + + First step of the tutorial. - Opens in gallery mode with zoom controls and navigation. + .. figure:: /_Images/step2.png + :alt: Step 2 + :zoom: gallery + :gallery: tutorial + + Second step - navigate with arrow keys. Example 5: Inline scroll-wheel zoom ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: rst - :linenos: .. figure:: /_Images/diagram.png :alt: Architecture diagram - :class: zoom-inline + :zoom: inline Use scroll wheel to zoom in/out directly on this image. @@ -189,14 +207,25 @@ Example 6: Magnifier lens ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: rst - :linenos: .. figure:: /_Images/detailed-ui.png :alt: User interface mockup - :class: zoom-lens + :zoom: lens Hover over the image to see a magnified view. +Example 7: Hidden zoom indicator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + + .. figure:: /_Images/screenshot.png + :alt: Screenshot + :zoom: lightbox + :zoom-indicator: false + + Lightbox without visible indicator icon. + Accessibility considerations ----------------------------- @@ -207,46 +236,45 @@ Keyboard navigation * **Lightbox and Gallery modes**: Full keyboard support - * :kbd:`Tab` - Navigate between controls + * :kbd:`Tab` - Navigate to image and controls * :kbd:`Enter` or :kbd:`Space` - Open lightbox/gallery - * :kbd:`ESC` - Close lightbox/gallery - * :kbd:`Arrow keys` - Navigate between images (gallery mode) - * :kbd:`+` / :kbd:`-` - Zoom in/out (gallery mode) + * :kbd:`Escape` - Close lightbox/gallery + * :kbd:`Arrow Left` / :kbd:`Arrow Right` - Navigate between images (gallery) + * :kbd:`+` / :kbd:`-` - Zoom in/out (gallery) * **Inline zoom mode**: Full keyboard support * :kbd:`Tab` - Focus the image * :kbd:`+` / :kbd:`-` - Zoom in/out * :kbd:`Arrow keys` - Pan when zoomed - * :kbd:`ESC` or :kbd:`0` - Reset zoom + * :kbd:`Escape` or :kbd:`0` - Reset zoom * **Lens mode**: Keyboard activation supported * :kbd:`Tab` - Focus the image * :kbd:`Enter` or :kbd:`Space` - Toggle lens on/off * :kbd:`Arrow keys` - Move lens position - * :kbd:`ESC` - Deactivate lens + * :kbd:`Escape` - Deactivate lens Screen reader support ~~~~~~~~~~~~~~~~~~~~~~ All zoom modes maintain proper ARIA attributes and provide descriptive -labels for assistive technologies. Always use the `:alt:` parameter to +labels for assistive technologies. Always use the `:alt:` option to provide descriptive alternative text for images. -JavaScript-free fallback -~~~~~~~~~~~~~~~~~~~~~~~~ +Reduced motion support +~~~~~~~~~~~~~~~~~~~~~~~ -The `zoom-css-only` mode provides a lightweight alternative that works -without JavaScript, ensuring accessibility for users with JavaScript -disabled or in restricted environments. +The zoom functionality respects the `prefers-reduced-motion` media query. +When reduced motion is preferred, transitions and animations are disabled. Best practices -------------- * Always include descriptive `:alt:` text for accessibility -* Use `zoom-lightbox` as the default for most images -* Consider `zoom-gallery` for related images that tell a story -* Use `zoom-inline` for technical diagrams that need frequent inspection -* Specify image width with `:width:` to prevent layout shifts +* Use `lightbox` as the default for most images +* Use `:gallery:` to group related images for navigation +* Use `inline` for technical diagrams that need frequent inspection +* Combine with `:class: with-border with-shadow` for better visual presentation * Test zoom functionality with keyboard navigation From ce9d3be7386255ad2b8c099b164ee4e63ab1ac6a Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sun, 28 Dec 2025 00:01:09 +0100 Subject: [PATCH 4/6] docs: add zoom-factor option and version note - Document :zoom-factor: option for lens mode magnification - Add versionadded directive noting feature requires v0.2.0+ --- .../Reference/ReStructuredText/Graphics/Images.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index 41fb9ceb..6115446c 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -89,6 +89,9 @@ Example 2: Image with caption and fixed width Image zoom and lightbox features ================================= +.. versionadded:: 0.2.0 + The image zoom feature was introduced in render-guides version 0.2.0. + The TYPO3 documentation theme provides built-in image zoom and lightbox features to enhance the viewing experience for images and figures. These features allow readers to view images in greater detail without leaving @@ -151,6 +154,10 @@ The following options are available for the figure and image directives: Whether to show the zoom indicator icon. Set to `false` to hide it. Default is `true` (shown). +`:zoom-factor:` + Magnification factor for lens mode. Default is `2`. Higher values + provide stronger magnification. Only used with `:zoom: lens`. + Usage examples -------------- From adfae692065d9b8ec742cd45e90e7a7a97223807 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Fri, 23 Jan 2026 10:02:12 +0100 Subject: [PATCH 5/6] fix: correct render-guides version to 0.36.0 --- Documentation/Reference/ReStructuredText/Graphics/Images.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index 6115446c..4398f4ef 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -89,8 +89,8 @@ Example 2: Image with caption and fixed width Image zoom and lightbox features ================================= -.. versionadded:: 0.2.0 - The image zoom feature was introduced in render-guides version 0.2.0. +.. versionadded:: 0.36.0 + The image zoom feature was introduced in render-guides version 0.36.0. The TYPO3 documentation theme provides built-in image zoom and lightbox features to enhance the viewing experience for images and figures. These From 894b17f1552d4d271f456552ac9f9ffeee82eaeb Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Fri, 23 Jan 2026 12:16:57 +0100 Subject: [PATCH 6/6] docs: add :zoom: lightbox to standard image examples Per review feedback, add :zoom: lightbox to the basic examples so users copying them will use zoom by default for screenshots. --- Documentation/Reference/ReStructuredText/Graphics/Images.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index 4398f4ef..dd48c738 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -38,6 +38,7 @@ Optional parameters for images and figures: * `:target:` link target * `:width:` : width of image, use for example px (for example `:width: 100px` * `:scale:` : scale images, for example `:scale: 65` +* `:zoom:` : enable zoom functionality (see :ref:`image-zoom`) Additional parameters can be found on the docutils page `reStructuredText Directives `__ @@ -52,6 +53,7 @@ Example 1: Scaled image with shadow and link target :target: https://typo3.org :class: with-shadow :scale: 50 + :zoom: lightbox .. code-block:: rst :linenos: @@ -61,6 +63,7 @@ Example 1: Scaled image with shadow and link target :target: https://typo3.org :class: with-shadow :scale: 50 + :zoom: lightbox .. _image-caption: @@ -71,6 +74,7 @@ Example 2: Image with caption and fixed width :alt: Left floating image :target: https://typo3.org :width: 100px + :zoom: lightbox This is the image caption @@ -81,6 +85,7 @@ Example 2: Image with caption and fixed width :alt: some image :target: https://typo3.org :width: 100px + :zoom: lightbox This is the image caption