Incubator escapee wiki:Extended image syntax

Template:Pp-semi-protected Template:Subcat guideline

This editing guideline documents the syntax used to insert pictures and other media files into Wikipedia pages. The same syntax is used regardless of whether a file is from Wikipedia or Wikimedia Commons. New editors are encouraged to also see the picture tutorial and the simple guide for beginners.

Brief syntaxEdit

In brief, the syntax for displaying an image is:

Plain type means you always type exactly what you see. Bold italics represent a variable, which you replace with its actual value.

Of the parameters shown, only Name is essential. Most images should use [[File:Name|thumb|alt=Alt|Caption]] and not specify a size.

The other details:

are optional and
can be placed in any order, except for Caption that has to be the last parameter.

Type: thumb (or thumbnail; either can be followed by =filename), frame (or framed), or frameless. Displays the image with specific formatting (see below).
Border: border. Put a small border around the image.
Location: right, left, center or none. Determine the horizontal placement of the image on the page. This defaults to right for thumbnails and framed images.
Alignment: baseline, middle, sub, super, text-top, text-bottom, top, or bottom. Vertically align the image with respect to adjacent text. This defaults to middle.
Size: upright or upright=scaling factor. Scale a thumbnail from its default size by the given factor (default 0.75), rounding the result to the nearest multiple of 10 pixels. The upright option must be used along with the thumb or frameless parameter. Alternatively, and only where absolutely necessary, users' preferences may be disregarded and the size of the image fixed by specifying a size in pixels: Width px or x Height px or Width x Height px. Scale the image to be no greater than the given width or height, keeping its aspect ratio. Scaling up (i.e. stretching the image to a greater size) is disabled when the image is framed.
Link: Link the image to a different resource, or to nothing.
Alt: Specify the alt text for the image. This is intended for visually impaired readers. See WP:ALT for how this should typically differ from the caption.
Page: Specify a page other than 1 to use for the thumbnail image in multipaged files.
Langtag: Specify the IETF language tag (slang: langtag) for switch-translated SVG (Scalable Vector Graphics) files. Some SVG files are multilingual; this parameter specifies which language to use. The langtag should be all lowercase (e.g., zh-hans rather than zh-Hans). Defaults to current Wikipedia language in article namespace or en in other namespaces. See Template:Tl2.
Caption: Not a keyword, the actual caption text. Must be last option. This is visible if the thumb or frame attribute is used, but may be displayed on mouseover in other cases.

Detailed syntaxEdit

The image syntax begins with [[, contains components separated by |, and ends with ]]. The [[ and the first | (or, if there is no |, the terminating ]]) must be on the same line; other spaces and line breaks Template:Tag (or Template:Tag) are ignored if they are next to | characters or just inside the brackets. Spaces or line breaks are not allowed just before the = in the following options, and may have undesirable side effects if they appear just after the =.

Do not terminate with the code |]]; this will be taken as an empty caption and override any real caption before it.

TypeEdit

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 Template:Myprefs). This is important to users with (e.g.) limited vision. If this is too large or small the 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.

Template:Anchorthumb (or thumbnail): 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 attribute. With an operand, e.g. thumb=Example.png, the operand names an image that is used as the thumbnail, ignoring any size specification.
frame: 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. Note: Any size options specified will be ignored and flagged as a 'bogus file option' by the Linter.
frameless: 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.

BorderEdit

border: Generate a one-pixel border around the image. This has an effect only around unframed images (those without Template:Para and Template:Para), as framed images always have borders.

LocationEdit

One of these options may be specified to control the position of the image. For examples of how all this works, see Examples of location parameter.

right: 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 thumb or frame is used.
left: 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 Template:Section link).
center: Place the image in the center of the page. The article text that follows the image is placed below the image.
none: 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 thumb nor frame: The image is placed inline with the text, File:Face-smile.svg like this.

Vertical alignmentEdit

One of these options may optionally be specified to control the vertical alignment of the image with respect to adjacent text.
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 thumb 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
of [[File:Flag of Hungary vertical.svg|option|frameless|upright=0.1|link=|alt=]]

Template:Div col middle:
File:Flag of Hungary vertical.svg(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.

baseline:
File:Flag of Hungary vertical.svgAlign the bottom of the image with the baseline of the text.

sub:
File:Flag of Hungary vertical.svgAlign 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₂".

super:
File:Flag of Hungary vertical.svgAlign 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²".

text-top:
File:Flag of Hungary vertical.svgAlign 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 ascenders in letters like lower-case "h".

text-bottom:
File:Flag of Hungary vertical.svgAlign the bottom of the image to the bottom of the text. This is somewhat lower than the baseline, because of descenders in letters like lower-case "y".

top:
File:Flag of Hungary vertical.svgAlign 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.

bottom:
File:Flag of Hungary vertical.svgAlign 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. Template:Div col end

SizeEdit

{{#invoke:Shortcut|main}} 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 'frame' is use, with the size options being flagged as a 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 upright or the default if possible.

Template:Collapse

(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.
upright Template:Nobold upright=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, upright=1.5 makes the image larger, which is useful for maps or schematics that need to be larger to be readable. The parameter upright=1 returns the same size as thumbnail width, and upright=0.75 is functionally identical to upright 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 upright option only works with the thumb or frameless parameter (see Type).
Widthpx: (E.g. 100px) Scale the image to make it the specified number of pixels in width, and scale the height to retain the original aspect ratio.
xHeightpx: (E.g., x150px) Scale the image to make it the specified number of pixels in height, and scale the width to retain the original aspect ratio.
WidthxHeightpx: (E.g. 100x150px) Scale the image to be no wider and no higher than the specified number of pixels. The image will keep its original aspect ratio.

LinkEdit

Template:See also

Template:Para: Ordinarily, clicking on an image takes the reader to the 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 Page is a URL, the reader will be taken outside the project; this is not normally done in article space.
Template:Para (alone): Disables the link so that clicking on the image does nothing.

Template:Para affects only what happens when the image itself is clicked; Template:Para images carry a little rectangle-rectangle icon File:Magnify-clip.svg 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 Template:Para should be used only with Template:Para images.

Template:Para cannot be used with Template:Para.

To disable all linking from, and description of, a purely decorative image Template:Sndso that it's ignored by screen readersTemplate:Snduse "Template:Para Template:Para" with no arguments for either parameter.

Alt text and captionEdit

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.Template:Update inline

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 "thumb". If you specify "frame" the caption does appear but any resizing (such as "125px") is ignored.

alt=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 ("thumbnail", "thumb", "frame" or "framed") then this text appears as a caption below the image. Otherwise, (if the image type is unspecified or is "frameless"), this text is used for the link title provided the link has not been suppressed with "|link=", and also for the alt text provided an explicit alt=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: alt is supported only for images. Audio and video files should use timed text.

ClassEdit

class=: 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 TemplateStyles.

The special class class=notpageimage will exclude the image from being selected by the Page Images algorithm.^{(phab:T301588)}
class=skin-invert will cause the image's colors to be inverted in dark mode. class=skin-invert-image will only invert the image and not the caption.
Separate multiple classes with spaces, e.g. class=skin-invert-image notpageimage

PageEdit

File:IMSLP01578-Ravel - Bolero Full Score Durand 1929.pdf

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 Template:Para: <syntaxhighlight lang="wikitext" inline>

File:IMSLP01578-Ravel - Bolero Full Score Durand 1929.pdf

Boléro: page 2 from the score

</syntaxhighlight>:

ExamplesEdit

Template:Dablink

Using the basic syntaxEdit

The most basic example uses the syntax <syntaxhighlight lang="wikitext" inline>Alt text</syntaxhighlight>. This does not scale the image or allow text to wrap around it. This is not normally appropriate in an article.

Alt text

This is rendered inline, and the specified text is used as the image's alt attribute (alternate text for programs which cannot display images, such as screen readers) and as the title attribute (supplementary text, often displayed as a tooltip when the mouse is over the image). See Wikipedia:Captions for discussion of appropriate caption text. See Wikipedia:Alternative text for images for discussion of appropriate alt text.

Above, the image of the Thames was put into its own paragraph. This isn't mandatory; images can sit inline in text, as shown below.

<syntaxhighlight lang="wikitext" style="overflow:auto;"> text text text text text text The Palace of Westminster text text text text text This is a globe. text text text text </syntaxhighlight>

gives

text text text text text text The Palace of Westminster text text text text text This is a globe. text text text text

Keeping the original size, with a captionEdit

To display an image as uploaded with a caption use [[File:Westminstpalace.jpg|frame|none|alt=Alt text|Caption text]].

Palace of Westminster	File:Westminstpalace.jpg From the Thames	`[[File:Westminstpalace.jpg\|thumb\|none\|100px\|alt=A large clock tower and other buildings line a great river.\|From the Thames]]`
Buckingham Palace	File:Buckingham Palace 2003.jpg Queen's home	`[[File:Buckingham Palace 2003.jpg\|thumb\|none\|100px\|alt=Grand city building below beautiful blue sky and clouds\|Queen's home]]`

	Code	Output
1.	`[[File:Accordion chords-01.ogg]]`	File:Accordion chords-01.ogg
2.	`[[File:Accordion chords-01.ogg\|frameless\|upright=1.3]]`	File:Accordion chords-01.ogg

	Code	Output
1.	`[[File:Accordion chords-01.ogg\|frameless\|upright=0.4\|left]] [[:File:Accordion chords-01.ogg\|Accordion chords]]`	File:Accordion chords-01.ogg Accordion chords
2.	`[[:File:Accordion chords-01.ogg\|Accordion chords]] [[File:Accordion chords-01.ogg\|90px\|right]]`	Accordion chords File:Accordion chords-01.ogg
3.	`[[:File:Accordion chords-01.ogg\|Accordion chords]] [[File:Accordion chords-01.ogg\|90px]]`	Accordion chords File:Accordion chords-01.ogg

Incubator escapee wiki:Extended image syntax

Brief syntaxEdit

Detailed syntaxEdit

TypeEdit

BorderEdit

LocationEdit

Vertical alignmentEdit

SizeEdit

LinkEdit

Alt text and captionEdit

ClassEdit

PageEdit

ExamplesEdit

Using the basic syntaxEdit

Keeping the original size, with a captionEdit

Aligning thumbnails to fit into textEdit

The many-floating-objects problemEdit

Section 1Edit

Section 2Edit

Using "upright"Edit

Using frameEdit

Using alignment "none" thumbnails in tablesEdit

Formatting and links in captionsEdit

Interaction between left-floating images and listsEdit

Overlaying annotations on an imageEdit

Superimposing imagesEdit

Cropping imagesEdit

Cancelling floating-around-image modeEdit

VR imagesEdit

Linking to the image without displaying itEdit

Sound filesEdit

MIDIEdit

Video filesEdit

Initial still imageEdit

Temporal media fragmentsEdit

Displaying small videos largerEdit

Thumbtime in a galleryEdit

See alsoEdit