From cc815d57c0f35ca8c3d2312d560b75d0bffe13e8 Mon Sep 17 00:00:00 2001 From: Franz Holzinger Date: Sun, 4 Jan 2026 15:01:53 +0100 Subject: [PATCH 1/5] WritingDocForExtension: Fix typos and improve clarity (#504) --- Documentation/Howto/WritingDocForExtension/Index.rst | 8 ++++---- Documentation/_Includes/_InitCommand.rst.txt | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/Howto/WritingDocForExtension/Index.rst b/Documentation/Howto/WritingDocForExtension/Index.rst index 6e689539..e49871da 100644 --- a/Documentation/Howto/WritingDocForExtension/Index.rst +++ b/Documentation/Howto/WritingDocForExtension/Index.rst @@ -24,14 +24,14 @@ Use the following Docker command to render your documentation guide locally: .. include:: /_Includes/_LocalRendering.rst.txt -The :ref:`render-documentation-with-docker` has more information. +See :ref:`render-documentation-with-docker` for more information. .. _how-to-start-docs-extension: Use the init command to create the Documentation folder ======================================================= -The following Docker command helps you to create some basic documentation +The following Docker command creates some basic documentation including the required configuration file :file:`Documentation/guides.xml`: .. include:: /_Includes/_InitCommand.rst.txt @@ -40,7 +40,7 @@ The command creates a folder :path:`Documentation` in the directory it is called from. This should be the root directory of your extension containing the `composer.json `_. -Follow the interactive dialoge. We suggest to use the option ReStructuredText (rst) +Follow the interactive dialog. We suggest to use the option ReStructuredText (rst) as this format provides the full power of the TYPO3 documentation theme. Using Markdown (md) is an option for simple and quick one page documentation. @@ -48,7 +48,7 @@ If your extension offers a main `Site set ` the new documentation. diff --git a/Documentation/_Includes/_InitCommand.rst.txt b/Documentation/_Includes/_InitCommand.rst.txt index cd2926c7..81af67c9 100644 --- a/Documentation/_Includes/_InitCommand.rst.txt +++ b/Documentation/_Includes/_InitCommand.rst.txt @@ -1,4 +1,4 @@ .. code-block:: bash - :caption: Execute in extension root, the directory that contains your extensions composer.json + :caption: Execute in extension root, the directory that contains your extension's composer.json docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest init From 68b46fe652160749fa9b9122083f5488739dfa99 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Fri, 23 Jan 2026 12:39:48 +0100 Subject: [PATCH 2/5] docs: document image zoom feature with :zoom: directive option (#503) * 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. * 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 * docs: update zoom syntax to use :zoom: option instead of class * 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+ * fix: correct render-guides version to 0.36.0 * 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. --- .../ReStructuredText/Graphics/Images.rst | 207 ++++++++++++++++++ 1 file changed, 207 insertions(+) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index 53a2a3c7..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,5 +85,208 @@ Example 2: Image with caption and fixed width :alt: some image :target: https://typo3.org :width: 100px + :zoom: lightbox This is the image caption + +.. _image-zoom: + +Image zoom and lightbox features +================================= + +.. 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 +features allow readers to view images in greater detail without leaving +the documentation page. + +Available zoom modes +-------------------- + +The zoom functionality is controlled by the `:zoom:` option on figure +and image directives. The following zoom modes are available: + +.. rst-class:: dl-parameters + +`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 Escape to close. A zoom indicator icon appears on the image. + + **Use case**: Screenshots, diagrams, and any image that benefits from + full-screen viewing. This is the recommended mode for most images. + +`gallery` + Click to open the image in a gallery viewer with mouse wheel zoom + 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 + collections that should be navigable together. + +`inline` + Enables scroll wheel zoom directly on the image without opening an + 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 without leaving context. + +`lens` + A magnifier lens follows the cursor when hovering over the image, + 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. + +Directive options +----------------- + +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). + +`:zoom-factor:` + Magnification factor for lens mode. Default is `2`. Higher values + provide stronger magnification. Only used with `:zoom: lens`. + +Usage examples +-------------- + +Example 3: Lightbox zoom +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: /_Images/a4.jpg + :alt: Example screenshot + :zoom: lightbox + :class: with-border with-shadow + + Click to open in lightbox. This is the recommended mode for most images. + +.. code-block:: rst + + .. figure:: /_Images/a4.jpg + :alt: Example screenshot + :zoom: lightbox + :class: with-border with-shadow + + Click to open in lightbox. + +Example 4: Gallery mode with grouped images +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + + .. figure:: /_Images/step1.png + :alt: Step 1 + :zoom: gallery + :gallery: tutorial + + First step of the tutorial. + + .. 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 + + .. figure:: /_Images/diagram.png + :alt: Architecture diagram + :zoom: inline + + Use scroll wheel to zoom in/out directly on this image. + +Example 6: Magnifier lens +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: rst + + .. figure:: /_Images/detailed-ui.png + :alt: User interface mockup + :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 +----------------------------- + +All zoom modes are designed with accessibility in mind: + +Keyboard navigation +~~~~~~~~~~~~~~~~~~~ + +* **Lightbox and Gallery modes**: Full keyboard support + + * :kbd:`Tab` - Navigate to image and controls + * :kbd:`Enter` or :kbd:`Space` - Open lightbox/gallery + * :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:`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:`Escape` - Deactivate lens + +Screen reader support +~~~~~~~~~~~~~~~~~~~~~~ + +All zoom modes maintain proper ARIA attributes and provide descriptive +labels for assistive technologies. Always use the `:alt:` option to +provide descriptive alternative text for images. + +Reduced motion support +~~~~~~~~~~~~~~~~~~~~~~~ + +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 `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 9b7cd6da4c328a27eafc98b44b915b43f9829fd3 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Tue, 27 Jan 2026 15:19:59 +0100 Subject: [PATCH 3/5] fix: resolve :target: and :zoom: conflict in image examples (#506) - Example 1: Remove :zoom: lightbox (demonstrates :target: for external links) - Example 2: Remove :target: (demonstrates :zoom: lightbox for zoom functionality) The :target: and :zoom: options conflict with each other. This change provides clear examples of both features without conflict. --- Documentation/Reference/ReStructuredText/Graphics/Images.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index dd48c738..e617c9b8 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -53,7 +53,6 @@ Example 1: Scaled image with shadow and link target :target: https://typo3.org :class: with-shadow :scale: 50 - :zoom: lightbox .. code-block:: rst :linenos: @@ -63,7 +62,6 @@ Example 1: Scaled image with shadow and link target :target: https://typo3.org :class: with-shadow :scale: 50 - :zoom: lightbox .. _image-caption: @@ -72,7 +70,6 @@ Example 2: Image with caption and fixed width .. figure:: /_Images/a4.jpg :alt: Left floating image - :target: https://typo3.org :width: 100px :zoom: lightbox @@ -83,7 +80,6 @@ Example 2: Image with caption and fixed width .. figure:: /_Images/a4.jpg :alt: some image - :target: https://typo3.org :width: 100px :zoom: lightbox From 625cae09bb221b9544759b19e738df4c8c762980 Mon Sep 17 00:00:00 2001 From: Franz Holzinger Date: Tue, 3 Feb 2026 08:04:03 +0100 Subject: [PATCH 4/5] Fix escape character notation in RstCheatSheet (#507) * Fix escape character notation in RstCheatSheet Is the backslash working by this change? * Apply suggestion from @linawolf * Apply suggestion from @linawolf --------- Co-authored-by: Lina Wolf <48202465+linawolf@users.noreply.github.com> --- Documentation/Basics/RstCheatSheet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Basics/RstCheatSheet.rst b/Documentation/Basics/RstCheatSheet.rst index f601071b..38e78c21 100644 --- a/Documentation/Basics/RstCheatSheet.rst +++ b/Documentation/Basics/RstCheatSheet.rst @@ -193,7 +193,7 @@ Escape characters ================= If you want to use a character, which would create some special reST markup, -with its normal meaning, you must escape it with a prepended "\". +with its normal meaning, you must escape it with a prepended :rst:`\`. For example surrounding text with "*" signs normally makes it show up in italics. By escaping the special characters "*" you make the stars normal text characters: From 7f6ce68f86d0e2acd58062104339183a35161ea8 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Thu, 12 Feb 2026 20:38:46 +0100 Subject: [PATCH 5/5] docs: document image/figure float and alignment options Add documentation for the float and alignment feature introduced in render-guides 0.37.0 (PR #1174). Covers CSS class approach (:class: float-left/float-right), the :align: option on figures, clearing floats with rst-class:: clear-both, and responsive behavior. Includes three live examples (Examples 8-10) and best practices. --- .../ReStructuredText/Graphics/Images.rst | 196 ++++++++++++++++++ 1 file changed, 196 insertions(+) diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index e617c9b8..3fa388f8 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -39,6 +39,10 @@ Optional parameters for images and figures: * `: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`) +* `:class:` : CSS classes, for example `with-shadow`, `with-border`, `float-left`, + `float-right` (see :ref:`image-float-alignment`) +* `:align:` : alignment/float for figures: `left`, `right`, `center` + (see :ref:`image-float-alignment`) Additional parameters can be found on the docutils page `reStructuredText Directives `__ @@ -286,3 +290,195 @@ Best practices * 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 + +.. _image-float-alignment: + +Image and figure floating and alignment +======================================== + +.. versionadded:: 0.37.0 + Float and alignment support for images and figures was introduced in + render-guides version 0.37.0. + +Images and figures can be floated to the left or right so that surrounding +text wraps around them. This is useful for inline illustrations, icons, +or any image that should be embedded within a text flow rather than +displayed as a standalone block. + +There are two ways to apply floating: + +1. **CSS classes** `:class: float-left` or `:class: float-right` — works on + both `.. image::` and `.. figure::` directives. +2. **`:align:` option** `:align: left`, `:align: right`, or `:align: center` + — works on `.. figure::` directives (internally mapped to the same CSS + classes). + +Both approaches produce the same visual result. Use whichever fits your +preference. + +Float with CSS classes +---------------------- + +Add `float-left` or `float-right` to the `:class:` option. You can combine +these with other classes such as `with-shadow` or `with-border`: + +.. code-block:: rst + + .. figure:: /Images/MyImage.png + :alt: Description of the image + :class: float-left with-shadow + + Caption text here + + Surrounding text will wrap to the right of the image. + +Align option +------------ + +The `:align:` option on `.. figure::` directives supports `left`, `right`, +and `center`. Values `left` and `right` produce the same floating behavior +as the CSS classes: + +.. code-block:: rst + + .. figure:: /Images/MyImage.png + :alt: Description of the image + :align: right + + Caption text here + + Surrounding text will wrap to the left of the image. + +Using `:align: center` centers the figure without any text wrapping. + +Clearing floats +---------------- + +After a floated image, you may want subsequent content to appear below the +image rather than wrapping around it. Use the `clear-both` class to clear +floats: + +.. code-block:: rst + + .. figure:: /Images/MyImage.png + :alt: Description of the image + :class: float-left + + Caption + + This text wraps around the image. + + .. rst-class:: clear-both + + This text appears below the image. + +The `.. rst-class:: clear-both` directive applies the CSS `clear: both` +property to the next element, forcing it below any floated content. + +Responsive behavior +------------------- + +Floated images automatically switch to full-width block display on small +screens (below 576px). This ensures readable text on mobile devices +without horizontal scrolling. + +Example 8: Figure floated left +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: /_Images/a4.jpg + :alt: Example figure floated left + :class: float-left with-shadow + :width: 150px + + A figure floated to the left + +Typesetting is the composition of text by means of arranging physical types +or the digital equivalents. Stored letters and other symbols are retrieved +and ordered according to a language's orthography for visual display. +Typesetting requires one or more fonts. + +.. rst-class:: clear-both + +.. code-block:: rst + + .. figure:: /_Images/a4.jpg + :alt: Example figure floated left + :class: float-left with-shadow + :width: 150px + + A figure floated to the left + + Typesetting is the composition of text by means of arranging + physical types or the digital equivalents. ... + + .. rst-class:: clear-both + +Example 9: Figure aligned right +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: /_Images/a4.jpg + :alt: Example figure aligned right + :align: right + :width: 150px + + A figure aligned right via :align: + +Typesetting is the composition of text by means of arranging physical types +or the digital equivalents. Stored letters and other symbols are retrieved +and ordered according to a language's orthography for visual display. +Typesetting requires one or more fonts. + +.. rst-class:: clear-both + +.. code-block:: rst + + .. figure:: /_Images/a4.jpg + :alt: Example figure aligned right + :align: right + :width: 150px + + A figure aligned right via :align: + + Typesetting is the composition of text by means of arranging + physical types or the digital equivalents. ... + + .. rst-class:: clear-both + +Example 10: Image floated left with shadow +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. image:: /_Images/a4.jpg + :alt: Example image floated left + :class: float-left with-shadow + :width: 150px + +Typesetting is the composition of text by means of arranging physical types +or the digital equivalents. Stored letters and other symbols are retrieved +and ordered according to a language's orthography for visual display. +Typesetting requires one or more fonts. + +.. rst-class:: clear-both + +.. code-block:: rst + + .. image:: /_Images/a4.jpg + :alt: Example image floated left + :class: float-left with-shadow + :width: 150px + + Typesetting is the composition of text by means of arranging + physical types or the digital equivalents. ... + + .. rst-class:: clear-both + +Best practices for floating +---------------------------- + +* Always use `.. rst-class:: clear-both` after floated content to prevent + layout issues with subsequent sections +* Set an explicit `:width:` on floated images to control how much space + text has to wrap around +* Floated figures are limited to 50% of the page width to ensure readability +* Prefer `:align:` on figures for cleaner RST syntax; use `:class:` when you + need to combine float with other classes like `with-shadow` +* Test on narrow viewports to verify the responsive behavior