From 1554fcddd76dd5fb5a23091f995de085301738c5 Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Sun, 27 Sep 2026 01:28:15 +0200 Subject: [PATCH 1/2] [TASK] Float images with :align: instead of float-left/float-right render-guides replaces the Bootstrap 4 classes float-left and float-right with float-start and float-end, and logs a deprecation warning when a document still uses the old names (TYPO3-Documentation/render-guides#1179). This guide recommended :class: float-left as the first way to float an image, and two of its live examples used it, so the guide itself would log two warnings. The guide now recommends :align:, which render-guides already maps on both image and figure, and keeps other classes such as with-shadow in :class: next to it. The class form is float-start / float-end, with a substitution image as its example: docutils only accepts top, middle and bottom for :align: inside a substitution definition. The page also says that the old class names are deprecated. Assisted-by: Claude Opus 5 Agent-Session: https://claude.ai/code/session_019F8MxNJMzB34gc68wg6Xkv Agent-Host: 0493f0 Signed-off-by: Sebastian Mendel --- .../Graphics/ImageAlignment.rst | 58 +++++++++++-------- .../ReStructuredText/Graphics/Images.rst | 6 +- 2 files changed, 37 insertions(+), 27 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst b/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst index 4979e830..6dd26a6a 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst @@ -18,47 +18,53 @@ displayed as a standalone block. There are two ways to apply floating: -1. **CSS classes** :rst:`:class: float-left` or :rst:`:class: float-right` — works on - both :rst:`.. image::` and :rst:`.. figure::` directives. -2. The :rst:`:align:` **option** — :rst:`:align: left`, :rst:`:align: right`, or :rst:`:align: center` - — works on :rst:`.. figure::` directives (internally mapped to the same CSS - classes). +1. The :rst:`:align:` **option** — :rst:`:align: left`, :rst:`:align: right`, or :rst:`:align: center` + — works on both :rst:`.. image::` and :rst:`.. figure::` directives. +2. **CSS classes** :rst:`:class: float-start` or :rst:`:class: float-end` — also works on + both directives. -Both approaches produce the same visual result. Use whichever fits your -preference. +Both approaches produce the same visual result. Prefer :rst:`:align:`. Use the +CSS classes where :rst:`:align:` cannot float an image, for example on a +substitution image (:rst:`|name|`): docutils only accepts :rst:`top`, +:rst:`middle` and :rst:`bottom` for :rst:`:align:` inside a substitution +definition. + +The Bootstrap 4 class names :rst:`float-left` and :rst:`float-right` are +deprecated. The renderer rewrites them to :rst:`float-start` and +:rst:`float-end` and logs a warning. .. _image-float-css-classes: Float with CSS classes ====================== -Add :rst:`float-left` or :rst:`float-right` to the :rst:`:class:` option. You can combine +Add :rst:`float-start` or :rst:`float-end` to the :rst:`:class:` option. You can combine these with other classes such as :rst:`with-shadow` or :rst:`with-border`: .. code-block:: rst - .. figure:: /Images/MyImage.png - :alt: Description of the image - :class: float-left with-shadow - - Caption text here + .. |logo| image:: /Images/MyLogo.png + :alt: Description of the logo + :class: float-start with-shadow - Surrounding text will wrap to the right of the image. + |logo| Surrounding text will wrap to the right of the logo. .. _image-float-align-option: Align option ============ -The :rst:`:align:` option on :rst:`.. figure::` directives supports :rst:`left`, :rst:`right`, -and :rst:`center`. Values :rst:`left` and :rst:`right` produce the same floating behavior -as the CSS classes: +The :rst:`:align:` option on :rst:`.. image::` and :rst:`.. figure::` directives supports +:rst:`left`, :rst:`right`, and :rst:`center`. Values :rst:`left` and :rst:`right` produce the +same floating behavior as the CSS classes. Other classes such as :rst:`with-shadow` +go into the :rst:`:class:` option next to it: .. code-block:: rst .. figure:: /Images/MyImage.png :alt: Description of the image :align: right + :class: with-shadow Caption text here @@ -79,7 +85,7 @@ floats: .. figure:: /Images/MyImage.png :alt: Description of the image - :class: float-left + :align: left Caption @@ -108,7 +114,8 @@ Example 8: figure floated left .. figure:: /_Images/a4.jpg :alt: Example figure floated left - :class: float-left with-shadow + :align: left + :class: with-shadow :width: 150px A figure floated to the left @@ -124,7 +131,8 @@ Typesetting requires one or more fonts. .. figure:: /_Images/a4.jpg :alt: Example figure floated left - :class: float-left with-shadow + :align: left + :class: with-shadow :width: 150px A figure floated to the left @@ -174,7 +182,8 @@ Example 10: image floated left with shadow .. image:: /_Images/a4.jpg :alt: Example image floated left - :class: float-left with-shadow + :align: left + :class: with-shadow :width: 150px Typesetting is the composition of text by means of arranging physical types @@ -188,7 +197,8 @@ Typesetting requires one or more fonts. .. image:: /_Images/a4.jpg :alt: Example image floated left - :class: float-left with-shadow + :align: left + :class: with-shadow :width: 150px Typesetting is the composition of text by means of arranging @@ -206,6 +216,6 @@ Best practices for floating * Set an explicit :rst:`: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 :rst:`:align:` on figures for cleaner RST syntax; use :rst:`:class:` when you - need to combine float with other classes like :rst:`with-shadow` +* Prefer :rst:`:align:` for floating; add other classes like :rst:`with-shadow` + with :rst:`:class:` next to it * Test on narrow viewports to verify the responsive behavior diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst index f93271e8..02ecf93a 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/Images.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/Images.rst @@ -40,9 +40,9 @@ 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:`floating and alignment `) -* `:align:` : alignment/float for figures: `left`, `right`, `center` +* `:class:` : CSS classes, for example `with-shadow`, `with-border`, `float-start`, + `float-end` (see :ref:`floating and alignment `) +* `:align:` : alignment/float for images and figures: `left`, `right`, `center` (see :ref:`floating and alignment `) Additional parameters can be found on the docutils page `reStructuredText Directives From efd1a324be381b697c659f8ad709272aced18b8a Mon Sep 17 00:00:00 2001 From: Sebastian Mendel Date: Tue, 29 Sep 2026 22:41:13 +0200 Subject: [PATCH 2/2] [TASK] Drop the float-with-CSS-classes section :align: floats both image and figure, and other classes such as with-shadow sit next to it in :class:, so a separate section for the float classes only repeats it. Its one argument, the substitution image, rests on a docutils limit that render-guides does not have. The page now leads with the align option. The image-float-css-classes anchor moves there so existing links keep working, and one paragraph still names float-start / float-end and the deprecated float-left / float-right. Assisted-by: Claude Opus 5.5 Agent-Session: https://claude.ai/code/session_01XzfnUQmxDxanqouHSEHHky Agent-Host: 32116e Signed-off-by: Sebastian Mendel --- .../Graphics/ImageAlignment.rst | 45 ++++--------------- 1 file changed, 9 insertions(+), 36 deletions(-) diff --git a/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst b/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst index 6dd26a6a..97389da9 100644 --- a/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst +++ b/Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst @@ -16,48 +16,16 @@ 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. The :rst:`:align:` **option** — :rst:`:align: left`, :rst:`:align: right`, or :rst:`:align: center` - — works on both :rst:`.. image::` and :rst:`.. figure::` directives. -2. **CSS classes** :rst:`:class: float-start` or :rst:`:class: float-end` — also works on - both directives. - -Both approaches produce the same visual result. Prefer :rst:`:align:`. Use the -CSS classes where :rst:`:align:` cannot float an image, for example on a -substitution image (:rst:`|name|`): docutils only accepts :rst:`top`, -:rst:`middle` and :rst:`bottom` for :rst:`:align:` inside a substitution -definition. - -The Bootstrap 4 class names :rst:`float-left` and :rst:`float-right` are -deprecated. The renderer rewrites them to :rst:`float-start` and -:rst:`float-end` and logs a warning. - .. _image-float-css-classes: - -Float with CSS classes -====================== - -Add :rst:`float-start` or :rst:`float-end` to the :rst:`:class:` option. You can combine -these with other classes such as :rst:`with-shadow` or :rst:`with-border`: - -.. code-block:: rst - - .. |logo| image:: /Images/MyLogo.png - :alt: Description of the logo - :class: float-start with-shadow - - |logo| Surrounding text will wrap to the right of the logo. - .. _image-float-align-option: Align option ============ -The :rst:`:align:` option on :rst:`.. image::` and :rst:`.. figure::` directives supports -:rst:`left`, :rst:`right`, and :rst:`center`. Values :rst:`left` and :rst:`right` produce the -same floating behavior as the CSS classes. Other classes such as :rst:`with-shadow` -go into the :rst:`:class:` option next to it: +Use the :rst:`:align:` option to float an image or figure. It works on both +:rst:`.. image::` and :rst:`.. figure::` directives and supports :rst:`left`, +:rst:`right`, and :rst:`center`. Other classes such as :rst:`with-shadow` go +into the :rst:`:class:` option next to it: .. code-block:: rst @@ -72,6 +40,11 @@ go into the :rst:`:class:` option next to it: Using :rst:`:align: center` centers the figure without any text wrapping. +The CSS classes :rst:`float-start` and :rst:`float-end` in :rst:`:class:` still +float an image the same way. The Bootstrap 4 class names :rst:`float-left` and +:rst:`float-right` are deprecated: the renderer rewrites them to +:rst:`float-start` and :rst:`float-end` and logs a warning. + .. _image-float-clearing: Clearing floats