Editing Incubator escapee wiki:Extended image syntax (section)

==Detailed syntax==
The image syntax begins with <code><nowiki>[[</nowiki></code>, contains components separated by <code>|</code>, and ends with <code><nowiki>]]</nowiki></code>. The <code><nowiki>[[</nowiki></code> and the first <code>|</code> (or, if there is no <code>|</code>, the terminating <code><nowiki>]]</nowiki></code>) must be on the same line; other spaces and line breaks {{tag|br|o}} (or {{tag|br|s}}) are ignored if they are next to <code>|</code> characters or just inside the brackets. Spaces or line breaks are not allowed just before the <code>=</code> in the following options, and may have undesirable side effects if they appear just after the <code>=</code>.

Do not terminate with the code <code style="color: #a00">|]]</code>; this will be taken as an ''empty'' caption and override any ''real'' caption before it.

===Type===
One of these options may be specified to control whether or not the image is scaled and/or given a border. For options that automatically scale the image, it's usually to 220px; logged-in users can modify this (at "Thumbnail size" under {{myprefs|Appearance|Files}}). This is important to users with (e.g.) limited vision. If this is too large or small the [[#Size|upright attribute]] can be used. Specifying a fixed size in pixels overrides all of this, but is unfriendly to users who need a larger image.
; {{anchor|filename}}<code>thumb</code> (or '''<code>thumbnail</code>''') : Automatically scale the image, and put a box around it. Show a caption if specified. '''Float''' the image on the '''right''' unless overridden with the [[#Location|location attribute]]. With an operand, e.g. <code>thumb=Example.png</code>, the operand names an image that is used as the thumbnail, ignoring any size specification.
; <code>frame</code> : Preserve the original image size, and put a box around the image. Show any caption below the image. '''Float''' the image on the '''right''' unless overridden with the location attribute. <small> Note: Any size options specified will be ignored and flagged as a 'bogus file option' by the Linter.</small>
; <code>frameless</code> : Automatically scale the image up or down. Place it '''inline''' with the text unless overridden with the location attribute.
; Nothing specified : Preserve the original image size, and do not add a border around the image. Place it '''inline''' with the text unless overridden with the location attribute. Do not show a caption. If no alt text is specifically requested, use the requested caption as alt text. This option is almost exclusively used in templates.

===Border===
; <code>border</code> : Generate a one-pixel border around the image. This has an effect only around unframed images (those without {{para||thumb}} and {{para||frame}}), as framed images always have borders.

===Location===
One of these options may be specified to control the position of the image. For examples of how all this works, see [[#New syntax for images|Examples of location parameter]].
; <code>right</code> : Place the image on the right side of the page. The article text that follows the image '''flows''' around the image. This is the default when <code>thumb</code> or <code>frame</code> is used.
; <code>left</code> : Place the image on the left side of the page. The article text that follows the image '''flows''' around the image, but there may be formatting issues with lists and indented text (see {{section link||Interaction between left-floating images and lists}}).
; <code>center</code> : Place the image in the center of the page. The article text that follows the image is placed '''below''' the image.
; <code>none</code> : Place the image on the left side of the page. The article text that follows the image is placed '''below''' the image.
; Nothing specified, and neither <code>thumb</code> nor <code>frame</code> : The image is placed '''inline''' with the text, [[File:Face-smile.svg|18px|alt=smiling emoji]] like this. <!-- The order (place/location) of the emoji is intentional, to make it clear that the image is inline ( according to user:Redrose64 { Diff.: https://en.wikipedia.org/w/index.php?title=Wikipedia:Extended_image_syntax&oldid=prev&diff=1180015774 } ) -->

===Vertical alignment===
One of these options may optionally be specified to control the vertical alignment of the image with respect to adjacent text.<br />
These vertical alignment options apply only to plain images, which do not cause breaks and are not floated (that is, they do not work with images that need text to flow around them. To make text flow around an image, place the image preceding the text and use the <code>thumb</code> parameter).

In the following list, each option's explanation is preceded by what ''[[:File:Flag of Hungary vertical.svg]]'' looks like when aligned using the listed option, using the markup<br />
of&nbsp;<code><nowiki>[[File:Flag of Hungary vertical.svg|</nowiki>''option''<nowiki>|frameless|upright=0.1|link=|alt=]]</nowiki></code>

{{div col}}
<span style="break-inside:avoid-column;"><code>middle</code>:<br /> [[File:Flag of Hungary vertical.svg|middle|frameless|upright=0.1|link=|alt=]](This is the default.) Align the vertical middle of the image with the baseline of the text plus half the [[x-height]] of the text, so that the image is vertically centered around a lower case "x" in the text.</span>

<span style="break-inside:avoid-column;"><code>baseline</code>:<br /> [[File:Flag of Hungary vertical.svg|baseline|frameless|upright=0.1|link=|alt=]]Align the bottom of the image with the [[Baseline (typography)|baseline]] of the text.</span>

<span style="break-inside:avoid-column;"><code>sub</code>:<br /> [[File:Flag of Hungary vertical.svg|sub|frameless|upright=0.1|link=|alt=]]Align the bottom of the image to the same level that the bottom of a subscript would be, such as the bottom of the "2" in "X<sub>2</sub>".</span>

<span style="break-inside:avoid-column;"><code>super</code>:<br /> [[File:Flag of Hungary vertical.svg|super|frameless|upright=0.1|link=|alt=]]Align the bottom of the image to the same level that the bottom of a superscript would be, such as the bottom of the "2" in "X<sup>2</sup>".</span>

<span style="break-inside:avoid-column;"><code>text-top</code>:<br /> [[File:Flag of Hungary vertical.svg|text-top|frameless|upright=0.1|link=|alt=]]Align the top of the image to the top of the text. This is often a bit higher than the top of a capital letter, because of [[Ascender (typography)|ascenders]] in letters like lower-case "h".</span>

<span style="break-inside:avoid-column;"><code>text-bottom</code>:<br /> [[File:Flag of Hungary vertical.svg|text-bottom|frameless|upright=0.1|link=|alt=]]Align the bottom of the image to the bottom of the text. This is somewhat lower than the baseline, because of [[descender]]s in letters like lower-case "y".</span>

<span style="break-inside:avoid-column;"><code>top</code>:<br /> [[File:Flag of Hungary vertical.svg|top|frameless|upright=0.1|link=|alt=]]Align the top of the image to the top of the line containing the text. Normally this is slightly higher than the top of the text, to make space between lines of text.</span>

<span style="break-inside:avoid-column;"><code>bottom</code>:<br /> [[File:Flag of Hungary vertical.svg|bottom|frameless|upright=0.1|link=|alt=]]Align the bottom of the image to the bottom of the line containing the text. Normally this is slightly lower than the bottom of the text.</span>
{{div col end}}

===Size===
{{Shortcut|WP:PICSIZE}}
Any or none of these options may be specified to control the size of the image. In the case of images with captions, if the image is already smaller than the requested size, then the image retains its original size (it is not enlarged). In the case of images without captions, the image will be enlarged or reduced to match the requested size. Sizing is disabled when the [[#Type|type 'frame']] is use, with the size options being flagged as a [[Special:LintErrors/bogus-image-options|bogus file option]] at [[:Special:LintErrors]].

The default thumbnail width can be set in the preferences, so '''specifying in px is not recommended''' in order to respect the users' preferences, which may be important for accessibility. Exceptions can, of course, be made, but do try to use <code>upright</code> or the default if possible.

{{collapse|2=Implementation details|float=right|1=
{{anchor|Implementation details}} Specifying a size does not just change the apparent image size using HTML; it actually generates a resized version of the image on the fly and links to it appropriately. This happens whether or not you specify the size in conjunction with "thumb".

This means the server does all the work of changing the image size, not the web browser of the user. Having the server do all the work means faster downloading of pages. It also means that larger images can be stored on the server without any slowdown by the browser (especially on dial up telephone lines). Only the data for the actual size on the page is transmitted.

An exception is animated GIF images. Animated GIF images are not processed by the server. When a smaller size is specified the original full sized animated GIF image is served. Whether the animated GIF image is subsequently scaled to fit the allotted space belongs to the capabilities of the receiving browser. Resizing an animated GIF image will significantly reduce its quality, without any reduction of download time.

When there are two or more "size" options of the same type, only the last one is valid. However, if both an upright and an absolute size are used together, the absolute size always takes precedence, regardless of where it appears in the options.
}}

; ''(nothing specified)'' : For thumbnails, use the size specified in preferences for logged in users, and use a size determined by resolution for users who are not logged in. For non-thumbnails, use the native size of the image.
; <code>upright</code> {{nobold|or}} <code>upright=</code>''scaling factor'' : Scale a thumbnail's size to ''scaling factor'' times the default thumbnail size, rounding the result to the nearest multiple of 10. For instance, <code>upright=1.5</code> makes the image larger, which is useful for maps or schematics that need to be larger to be readable. The parameter <code>upright=1</code> returns the same size as thumbnail width, and <code>upright=0.75</code> is functionally identical to <code>upright</code> alone. If you set ''scaling factor'' equal to the image's aspect ratio (width divided by height) the result is equivalent to scaling the height to be equal to the normal thumbnail width.
: The <code>upright</code> option only works with the <code>thumb</code> or <code>frameless</code> parameter (see [[#Type|Type]]).
; ''Width''<code>px</code> : (''E.g.'' <code>100px</code>) Scale the image to make it the specified number of pixels in width, and scale the height to retain the original aspect ratio.
; <code>x</code>''Height''<code>px</code> : (''E.g.'', <code>x150px</code>) Scale the image to make it the specified number of pixels in height, and scale the width to retain the original aspect ratio.
; ''Width''<code>x</code>''Height''<code>px</code> : (''E.g.'' <code>100x150px</code>) Scale the image to be no wider and no higher than the specified number of pixels. The image '''will keep''' its original aspect ratio.

===Link===
{{see also|Wikipedia:Images linking to articles}}

; {{para|link|<var>Page</var>}} : Ordinarily, clicking on an image takes the reader to the [[Help:Image page|image description page]]. The link option allows the reader to be taken instead to a different page, such as a fuller image from which the thumbnail was cropped, or to a full document of which the thumbnail was a single page (or crop of a single page). Do not enclose the page name in square brackets. If <var>Page</var> is a URL, the reader will be taken outside the project; this is not normally done in article space.
; {{para|link}} (alone): Disables the link so that clicking on the image does nothing.

{{para|link}} affects only what happens when the ''image itself'' is clicked; {{para||thumb}} images carry a little rectangle-rectangle icon [[File:Magnify-clip.svg|15px|link=]] in the caption area, and clicking that always leads to the image description page. Except for public-domain images, it must always be possible for the reader to reach the image-description page, so {{para|link}} should be used only with {{para||thumb}} images.

{{para|link}} cannot be used with {{para||frame}}.

To disable all linking from, and description of, a [[Wikipedia:Manual of Style/Accessibility/Alternative text for images#Decorative images|purely decorative image]]{{snd}}so that it's ignored by screen readers{{snd}}use "{{para|link}}{{para|alt}}" with no arguments for either parameter.

===Alt text and caption===
Zero or more of these options may be specified to control the ''alt text'', ''link title'', and ''caption'' for the image. Captions may contain embedded wiki markup, such as links or formatting. See [[Wikipedia:Captions]] for discussion of appropriate caption text. See [[Wikipedia:Alternative text for images]] for discussion of appropriate alt text. Internet Explorer displays the link title as a tooltip but other browsers may not.{{Update inline|date=June 2024|reason=Internet Explorer is obsolete.}}

Hint: to force the caption to be written (underneath the picture) and not just appear as "hover text" even when you wish to resize the image, specify "<code>thumb</code>". If you specify "<code>frame</code>" the caption does appear but any resizing (such as "<code>125px</code>") is ignored.

; <code>alt=</code>''Alt'': Use '''''Alt''''' as the alt text for the image.
; ''Caption'': (the last option that is not recognised as some other part of the image syntax): How this text is used depends on the image type. When the type has a visible caption ("<code>thumbnail</code>", "<code>thumb</code>", "<code>frame</code>" or "<code>framed</code>") then this text appears as a caption below the image. Otherwise, (if the image type is unspecified or is "<code>frameless</code>"), this text is used for the link title provided the link has not been suppressed with "<code>|link=</code>", and also for the alt text provided an explicit <code>alt=</code>'''''Alt''''' has not been supplied.

The actual alt text for the displayed image will be one of the following, in order of preference:
# The explicitly requested '''''Alt''''', if any;
# The explicitly requested '''''Caption''''', if the image type has no visible caption;
# The empty string, if there is an explicitly requested '''''Caption''''' and the image type has a visible caption.
# The image file name if there is no explicitly requested '''''Alt''''' or '''''Caption'''''. This is never a satisfactory option.

It is possible to specify the link title text only for images with no visible caption (as described above). However, as not all browsers display this text, and it is ignored by screen readers, there is little point.

'''Note:''' <code>alt</code> is supported only for images. Audio and video files should use [[Wikipedia:Manual_of_Style/Accessibility#Video|timed text]].

===Class===
; <code>class=</code> : Used to insert any HTML classes for image. This has an effect only for classes listed specifically in [[Wikipedia:Catalogue of CSS classes]], or some classes produced by [[Wikipedia:TemplateStyles|TemplateStyles]].
*The special class <code>class=notpageimage</code> will exclude the image from being selected by the [[:mw:Extension:PageImages|Page Images]] algorithm.<sup>([[phab:T301588]])</sup>
*<code>class=skin-invert</code> will cause the image's colors to be inverted in [[mw:Reading/Web/Accessibility for reading/Updates/2024-04|dark mode]]. <code>class=skin-invert-image</code> will only invert the image and not the caption.
*Separate multiple classes with spaces, e.g. <code>class=skin-invert-image notpageimage</code>

===Page===
[[File:IMSLP01578-Ravel - Bolero Full Score Durand 1929.pdf|thumb|page=2|''Boléro'': page 2 from the score]]
Normally page 1 from a PDF or DjVu file is used to generate the thumbnail. A different page can be used with the parameter {{para|page}}: <syntaxhighlight lang="wikitext" inline>[[File:IMSLP01578-Ravel - Bolero Full Score Durand 1929.pdf|thumb|page=2|''Boléro'': page 2 from the score]]</syntaxhighlight>:
{{clear|right}}