Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
CybotTM wants to merge 4 commits into
base: main
Choose a base branch
from
Open

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

CybotTM wants to merge 4 commits into from

Conversation

@CybotTM
Copy link

@CybotTM CybotTM commented Dec 22, 2025 •
edited
Loading

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 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:
  3. Usage Examples - Practical RST code examples for each mode
  4. Accessibility Considerations - Keyboard navigation, screen reader support
  5. Best Practices - Guidance on when to use each mode

@CybotTM
Document image zoom and lightbox features
63bf832 
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.
@CybotTM CybotTM mentioned this pull request Dec 22, 2025
Merged
7 tasks
@CybotTM
Fix keyboard navigation docs for Inline and Lens modes
e074a09 
- Inline zoom has full keyboard support: Tab, +/-, arrows, ESC/0
- Lens mode has keyboard activation: Tab, Enter/Space, arrows, ESC
@CybotTM
docs: update zoom syntax to use :zoom: option instead of class
f1f7060
@CybotTM CybotTM changed the title Document image zoom/lightbox feature for figures docs: document image zoom feature with :zoom: directive option Dec 27, 2025
@CybotTM
docs: add zoom-factor option and version note
3e6150d 
- Document :zoom-factor: option for lens mode magnification
- Add versionadded directive noting feature requires v0.2.0+
@sarahmccarthy123
Copy link
Contributor

sarahmccarthy123 commented Jan 13, 2026

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
Author

CybotTM commented Jan 13, 2026 •
edited
Loading

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
linawolf reviewed Jan 18, 2026
View reviewed changes
Documentation/Reference/ReStructuredText/Graphics/Images.rst
=================================

.. versionadded:: 0.2.0
The image zoom feature was introduced in render-guides version 0.2.0.
Copy link
Member

@linawolf linawolf Jan 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0.36.0

@linawolf
Copy link
Member

linawolf commented Jan 18, 2026

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

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

Reviewers

@linawolf linawolf linawolf left review comments

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@CybotTM @sarahmccarthy123 @linawolf