Skip to content

docs: document image zoom feature with :zoom: directive option#503

Merged
linawolf merged 6 commits intoTYPO3-Documentation:mainfrom
CybotTM:feature/document-image-zoom
Jan 23, 2026
Merged

docs: document image zoom feature with :zoom: directive option#503
linawolf merged 6 commits intoTYPO3-Documentation:mainfrom
CybotTM:feature/document-image-zoom

Conversation

@CybotTM
Copy link
Contributor

@CybotTM CybotTM commented Dec 22, 2025

Summary

Documents the new image zoom/lightbox feature available in the TYPO3 documentation theme.

Related

Directive Options Documented

  • :zoom: - The zoom mode (lightbox, gallery, inline, lens)
  • :gallery: - Group name for gallery navigation
  • :zoom-indicator: - Show/hide the zoom indicator icon
  • :zoom-factor: - Magnification factor for lens mode (default: 2)

Zoom Modes

Mode Description
lightbox Click to open in full-screen overlay dialog
gallery Gallery viewer with navigation between grouped images
inline Scroll wheel zoom directly on image with pan
lens Magnifier lens follows cursor on hover

Example Usage

..  figure:: /Images/screenshot.png
    :alt: Example screenshot
    :zoom: lightbox
    :class: with-border with-shadow

    Click to open in lightbox.

..  figure:: /Images/step1.png
    :alt: Step 1
    :zoom: gallery
    :gallery: tutorial

    First step of the tutorial.

Sections Added

  1. Available Zoom Modes - Detailed descriptions and use cases
  2. Directive Options - :zoom:, :gallery:, :zoom-indicator:, :zoom-factor:
  3. Usage Examples - Practical RST code examples for each mode
  4. Accessibility Considerations - Keyboard navigation, screen reader support, reduced motion
  5. Best Practices - Guidance on when to use each mode

Updates

  • Added :zoom: lightbox to standard image examples per review feedback
  • Corrected render-guides version to 0.36.0

@CybotTM CybotTM changed the title Document image zoom/lightbox feature for figures docs: document image zoom feature with :zoom: directive option Dec 27, 2025
@sarahmccarthy123
Copy link
Contributor

When I render this locally and click on the image for Example 3: Lightbox zoom (Documentation/Reference/ReStructuredText/Graphics/Images.rst) it doesn't seem to open in a lightbox.

@CybotTM
Copy link
Contributor Author

CybotTM commented Jan 13, 2026

Hi @sarahmccarthy123,

When I render this locally and click on the image for Example 3: Lightbox zoom (Documentation/Reference/ReStructuredText/Graphics/Images.rst) it doesn't seem to open in a lightbox.

This requires Implementation PR: TYPO3-Documentation/render-guides#1139

@linawolf
Copy link
Member

I think it might be a good idea to add :zoom: lightbox as standart to all situations where screenshots are displayed. As ppl tend to just copy the easy examples

CybotTM and others added 5 commits January 23, 2026 10:02
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.
- Inline zoom has full keyboard support: Tab, +/-, arrows, ESC/0
- Lens mode has keyboard activation: Tab, Enter/Space, arrows, ESC
- Document :zoom-factor: option for lens mode magnification
- Add versionadded directive noting feature requires v0.2.0+
@CybotTM CybotTM force-pushed the feature/document-image-zoom branch from 3e6150d to adfae69 Compare January 23, 2026 09:02
@CybotTM
Copy link
Contributor Author

CybotTM commented Jan 23, 2026

Hi @linawolf ,

I think it might be a good idea to add :zoom: lightbox as standart to all situations where screenshots are displayed. As ppl tend to just copy the easy examples

Yes, but someone needs to decide on this. And this is not related to this PR, is it?
This needs to be applied in TYPO3-Documentation/render-guides - or did I miss something?

Per review feedback, add :zoom: lightbox to the basic examples
so users copying them will use zoom by default for screenshots.
@CybotTM
Copy link
Contributor Author

CybotTM commented Jan 23, 2026

Added :zoom: lightbox to the standard image examples (Example 1 and Example 2) per your suggestion. This way users copying these examples will have zoom enabled by default.

@linawolf linawolf merged commit 68b46fe into TYPO3-Documentation:main Jan 23, 2026
1 check passed
@CybotTM
Copy link
Contributor Author

CybotTM commented Jan 23, 2026

Hey @linawolf ,

https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Graphics/Images.html#example-1-scaled-image-with-shadow-and-link-target

..  figure:: /_Images/a4.jpg
    :alt: some image
    :target: https://typo3.org
    :class: with-shadow
    :scale: 50
    :zoom: lightbox

target and zoom collide here, in general zoom seems do not make much sense here with scale.

What do you think?

@linawolf
Copy link
Member

then we should maybe remove the zoom there?

@linawolf
Copy link
Member

Woould you like to make a follow up

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants