Skip to content

Commit d9f27c3

Browse files
CybotTMCybotTM
committed
docs: document image/figure float and alignment options
Add documentation for the new CSS float and alignment support for images and figures introduced in render-guides 0.37.0. Split the monolithic Images.rst into three focused pages: - Images.rst: basics, parameters, Examples 1-2 - ImageZoom.rst: zoom modes, options, accessibility, Examples 3-7 - ImageAlignment.rst: float/align, clearing, responsive, Examples 8-10 Depends on: TYPO3-Documentation/render-guides#1174
1 parent 625cae0 commit d9f27c3

4 files changed

Lines changed: 407 additions & 204 deletions

File tree

‎Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst‎

Lines changed: 195 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
:navigation-title: Float and alignment
2+
3+
.. include:: /Includes.rst.txt
4+
.. _image-float-alignment:
5+
6+
==========================================
7+
Image and figure floating and alignment
8+
==========================================
9+
10+
.. versionadded:: 0.37.0
11+
Float and alignment support for images and figures was introduced in
12+
render-guides version 0.37.0.
13+
14+
Images and figures can be floated to the left or right so that surrounding
15+
text wraps around them. This is useful for inline illustrations, icons,
16+
or any image that should be embedded within a text flow rather than
17+
displayed as a standalone block.
18+
19+
There are two ways to apply floating:
20+
21+
1. **CSS classes** ``:class: float-left`` or ``:class: float-right`` — works on
22+
both ``.. image::`` and ``.. figure::`` directives.
23+
2. The ``:align:`` **option** — ``:align: left``, ``:align: right``, or ``:align: center``
24+
— works on ``.. figure::`` directives (internally mapped to the same CSS
25+
classes).
26+
27+
Both approaches produce the same visual result. Use whichever fits your
28+
preference.
29+
30+
Float with CSS classes
31+
----------------------
32+
33+
Add ``float-left`` or ``float-right`` to the ``:class:`` option. You can combine
34+
these with other classes such as ``with-shadow`` or ``with-border``:
35+
36+
.. code-block:: rst
37+
38+
.. figure:: /Images/MyImage.png
39+
:alt: Description of the image
40+
:class: float-left with-shadow
41+
42+
Caption text here
43+
44+
Surrounding text will wrap to the right of the image.
45+
46+
Align option
47+
------------
48+
49+
The ``:align:`` option on ``.. figure::`` directives supports ``left``, ``right``,
50+
and ``center``. Values ``left`` and ``right`` produce the same floating behavior
51+
as the CSS classes:
52+
53+
.. code-block:: rst
54+
55+
.. figure:: /Images/MyImage.png
56+
:alt: Description of the image
57+
:align: right
58+
59+
Caption text here
60+
61+
Surrounding text will wrap to the left of the image.
62+
63+
Using ``:align: center`` centers the figure without any text wrapping.
64+
65+
Clearing floats
66+
---------------
67+
68+
After a floated image, you may want subsequent content to appear below the
69+
image rather than wrapping around it. Use the ``clear-both`` class to clear
70+
floats:
71+
72+
.. code-block:: rst
73+
74+
.. figure:: /Images/MyImage.png
75+
:alt: Description of the image
76+
:class: float-left
77+
78+
Caption
79+
80+
This text wraps around the image.
81+
82+
.. rst-class:: clear-both
83+
84+
This text appears below the image.
85+
86+
The ``.. rst-class:: clear-both`` directive applies the CSS ``clear: both``
87+
property to the next element, forcing it below any floated content.
88+
89+
Responsive behavior
90+
-------------------
91+
92+
Floated images automatically switch to full-width block display on small
93+
screens (below 576px). This ensures readable text on mobile devices
94+
without horizontal scrolling.
95+
96+
Example 8: Figure floated left
97+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
99+
.. figure:: /_Images/a4.jpg
100+
:alt: Example figure floated left
101+
:class: float-left with-shadow
102+
:width: 150px
103+
104+
A figure floated to the left
105+
106+
Typesetting is the composition of text by means of arranging physical types
107+
or the digital equivalents. Stored letters and other symbols are retrieved
108+
and ordered according to a language's orthography for visual display.
109+
Typesetting requires one or more fonts.
110+
111+
.. rst-class:: clear-both
112+
113+
.. code-block:: rst
114+
115+
.. figure:: /_Images/a4.jpg
116+
:alt: Example figure floated left
117+
:class: float-left with-shadow
118+
:width: 150px
119+
120+
A figure floated to the left
121+
122+
Typesetting is the composition of text by means of arranging
123+
physical types or the digital equivalents. ...
124+
125+
.. rst-class:: clear-both
126+
127+
Example 9: Figure aligned right
128+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129+
130+
.. figure:: /_Images/a4.jpg
131+
:alt: Example figure aligned right
132+
:align: right
133+
:width: 150px
134+
135+
A figure aligned right via ``:align:``
136+
137+
Typesetting is the composition of text by means of arranging physical types
138+
or the digital equivalents. Stored letters and other symbols are retrieved
139+
and ordered according to a language's orthography for visual display.
140+
Typesetting requires one or more fonts.
141+
142+
.. rst-class:: clear-both
143+
144+
.. code-block:: rst
145+
146+
.. figure:: /_Images/a4.jpg
147+
:alt: Example figure aligned right
148+
:align: right
149+
:width: 150px
150+
151+
A figure aligned right via :align:
152+
153+
Typesetting is the composition of text by means of arranging
154+
physical types or the digital equivalents. ...
155+
156+
.. rst-class:: clear-both
157+
158+
Example 10: Image floated left with shadow
159+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160+
161+
.. image:: /_Images/a4.jpg
162+
:alt: Example image floated left
163+
:class: float-left with-shadow
164+
:width: 150px
165+
166+
Typesetting is the composition of text by means of arranging physical types
167+
or the digital equivalents. Stored letters and other symbols are retrieved
168+
and ordered according to a language's orthography for visual display.
169+
Typesetting requires one or more fonts.
170+
171+
.. rst-class:: clear-both
172+
173+
.. code-block:: rst
174+
175+
.. image:: /_Images/a4.jpg
176+
:alt: Example image floated left
177+
:class: float-left with-shadow
178+
:width: 150px
179+
180+
Typesetting is the composition of text by means of arranging
181+
physical types or the digital equivalents. ...
182+
183+
.. rst-class:: clear-both
184+
185+
Best practices for floating
186+
----------------------------
187+
188+
* Always use ``.. rst-class:: clear-both`` after floated content to prevent
189+
layout issues with subsequent sections
190+
* Set an explicit ``:width:`` on floated images to control how much space
191+
text has to wrap around
192+
* Floated figures are limited to 50% of the page width to ensure readability
193+
* Prefer ``:align:`` on figures for cleaner RST syntax; use ``:class:`` when you
194+
need to combine float with other classes like ``with-shadow``
195+
* Test on narrow viewports to verify the responsive behavior

0 commit comments

Comments
 (0)