Adjuta: Stilos de patrono

This page is a translated version of the page Help:TemplateStyles and the translation is 22% complete.

Outdated translations are marked like this.

Nota: Si tu modifica iste pagina, tu accepta de publicar tu contribution sub licentia CC0. Vide le paginas de adjuta sur le dominio public pro saper plus.

TemplateStyles permitte le stilisation comportamental e esthetic complexe de patronos per le uso de files CSS externe, que illos mesme es paginas wiki. Notabilemente, le capacitate de crear/modificar le files CSS es includite in le permissiones predefinite pro usatores autoconfirmate e dunque non require involver alicuno con privilegios de administrator del interfacie.

Como functiona?

Redactores pote adder <templatestyles src="[qualque pagina]" /> a un pagina, e le contento del pagina referite essera analysate como CSS, normalisate e cargate in paginas ubi le etiquetta ‎<templatestyles> es usate (sia directemente, sia transcludite per un patrono usate sur le pagina).

[qualque pagina] debe haber le modello de contento sanitized-css (CSS sanificate), le qual es predefinite pro subpaginas in le spatio de nomines Patrono con nomines que termina in .css. Le maniera de uso recommendate es immagazinar le stilos pro Patrono:Exemplo in un subpagina del patrono sur que illos ha le plus influentia, como Patrono:Exemplo/stilo.css. Si [qualque pagina] non ha prefixo de spatio de nomines, illo usara le spatio de nomines Patrono. Dunque, per exemplo, <templatestyles src="Foo/styles.css" /> cargara Patrono:Foo/styles.css.

Le etiquetta ‎<templatestyles> debe esser placiate ante le contento que es stilisate, idealmente al summitate del patrono o le plus proxime a illac possibile, pro evitar un potential flash de contento non stilisate si le pagina deveni initialmente visibile durante que illo es ancora solo partialmente rendite.

Qual problemas resolve isto?

TemplateStyles permitte al redactores associar regulas de stilo a paginas specific. Illo forni tote le possibilitates de folios de stilo CSS, ma filtra constructos periculose, e functiona con utensiles de previsualisation/depuration (como TemplateSandbox ) como on expectarea.

Diminuer le barriera de accesso e mantenentia resultara, on spera, in plus innovation in le disposition visual de patronos, minus costo de mantenentia, e melior adaptabilitate a optiones de schermo (specialmente con dispositivos mobile que constitue plus que le medio del visitas de paginas de Wikipedia mesmo desde 30 de martio 2016).

Traditionalmente, il habeva duo manieras pro stilisar patronos (o qualcunque altere contento) sur paginas de MediaWiki, e necun del approches functionava multo ben:

Uso de stilos integrate (isto vole dicer: codice HTML crude con addition de attributos como style="margin: 10px;")
Uso de certe messages de systema special como MediaWiki:Common.css

Pro stilos integrate

Il non ha separation inter contento e presentation. In casos ubi le contento non veni de un patrono (per exemplo, tabellas in articulos), isto resultara in wikitexto de articulo que es incomprensibile pro le majoritate del redactores.
Perque le stilos se misce con wikitexto, le coloration syntactic e altere formas de supporto pro le modification de CSS es difficile o impossibile.
Le stilos debe esser repetite pro cata elemento HTML al qual illos se applica, lo que resulta in multe copiar-collar e in codice que es difficile a leger e mantener.

Le attributos de stilo es limitate a un subinsimul de CSS. Lo plus importante es que le regulas @media necessari pro le conception web responsive non functiona, dunque, es impossibile facer patronos que functiona ben sur un grande varietate de dimensiones de schermo. In plus, le stilos integrate ha precedentia super le folios de stilo CSS, dunque le adaptation specific pro usatores, apparentias o dispositivos deveni plus difficile.

Most importantly, @media rules needed for responsive design do not work so it's impossible to make templates that work well over a wide range of screen sizes. Furthermore, inline styles take precedence over CSS stylesheets so user-, skin- or device-specific customizations become more difficult.

Pro paginas de systema (MediaWiki:*.css)

Le modification es limitate al administratores de interfacie , lo que constitue un grande obstaculo al participation.
Le restrictiones de modification non pote esser levate perque il non ha un maniera de limitar le regulas CSS que pote esser usate, e alcunes de illos poterea esser abusate pro traciar le adresses IP del lectores o mesmo pro executar scripts in alicun navigatores ancian.
Es impossibile testar le modificationes sin publicar primo. T112474
Tote le folios de stilo debe esser cargate in tote le paginas (non importa si illos los usa), lo que dissipa largor de banda e rende difficile le recerca de errores in regulas de stilo.

Es secur?

Si! TemplateStyles include un analysator CSS complete que lege, re-serialisa e escappa tote le codice e remove le regulas CSS que illo non recognosce. Le analysator es sufficientemente precise pro rejectar ressources distante (como imagines de fundo) ma permitter los local. Le selectores CSS es rescribite de maniera que illos non pote referer a elementos foras del contento del articulo. (Non es actualmente impedite le modification visual de areas foras del contento del articulo per displaciar partes del articulo, per exemplo via positionamento absolute. Nonobstante, tal cosa esseva ja possibile anteriormente con wikitexto e stilos integrate.) CSS selectors are rewritten so that they cannot refer to elements outside article content. (Visually modifying areas outside article content by displacing parts of the article, e.g. via absolute positioning, is not prevented at this time. This is no change from the status quo, as such a thing was already possible with wikitext and inline styles.)

Allowed CSS properties and rules

As of 5 martio 2025, TemplateStyles accepts no fewer than 331 CSS properties and aliases, including the vast majority of those most often used on the modern internet with official support by one or more major web browser. Beyond simple rules, @media, @page, @supports, @keyframe, @font-face/@font-feature-values at-rules are also supported (with font-face restricted to fonts whose name starts with TemplateStyles, for security reasons).

The CSS var() function is permitted only in properties taking a single color value and inside calc()functions. Setting custom properties is not permitted.

CSS property declarations permitted by css-sanitizer ^[a]^[b]^[c]

Note: Each property is linked to a source of documentation on its usage, however the typical external link icons have been suppressed to prevent the obscuring of any links to footnotes that similarly appear in superscript.

Notas:

↑ This list is current as of changeset ffe10a21512f to the css-sanitizer source code repository, authored at 20:34, 5 martio 2025.
↑ The authoritative reference for these properties will always be the source code for the css-sanitizer library, specifically the src/Sanitizer/StylePropertySanitizer.php file. When reviewing it, a simple method for bringing them into greater focus is to perform a full text search of the contents for the string $props.
↑ Non-standard properties—including those with vendor prefixes, except for the vendor-prefixed -*-user-select group—have never been recognized by this extension and continue to be automatically rejected, as of 2 de januario 2024; see phab:T162379: Decide which non-standard CSS properties to support in TemplateStyles for notice of any progress on a resolution to this issue.
↑ The modern block-ellipsis property is present in the extension source code only by its original name, block-overflow (StylePropertySanitizer.php). Though the property was renamed during drafting by the W3C-CSSWG in 24 de augusto 2018 and is now only a legacy alias, until the extension is updated only the original property name is accepted as valid.
↑ ^5.0 ^5.1 ^5.2 ^5.3 ^5.4 ^5.5 ^5.6 ^5.7 The page-break-* properties from CSS2 were deprecated by the W3C-CSSWG in 15 de septembre 2018 and persist only as legacy shorthands for the break-* replacement properties from the CSS3 Fragmentation module. They are subject to removal in the future and users are strenuously encouraged to replace all uses of the older properties explicitly, paying attention to the fact that not all values have a 1:1 equivalent mapping with the replacements' values. Several popular user agents have already demonstrated flawed and inconsistent behavior when the legacy shorthands are present on a page.
↑ The ~~clip~~ property was deprecated by the W3C-CSSWG in 22 de julio 2018, and official guidance was added to use the clip-path property in its place; it is subject to removal at any time due to definition conflicts with other properties.
↑ The legacy name alias grid-column-gap is also accepted as valid by this extension and is evaluated exactly as if its modern replacement property name, column-gap, had been used.
↑ The modern continue property, which is accepted by this extension, must always be used in place of the older region-fragment property, which it never accepted as valid. The W3C-CSSWG describes 'continue' as generalizing the older property ahead of replacing it altogether, but care must be taken during the conversion as different values must be defined to achieve identical behaviors between the two.
↑ The modern font-width property is present in the extension source code only by its original name, font-stretch (StylePropertySanitizer.php). Though the original name was deprecated by the W3C-CSSWG in 23 de januario 2024 and remains only as a legacy alias, until the extension is updated only the original property name is accepted as valid.
↑ The legacy name alias grid-gap is also accepted as valid by this extension and is evaluated exactly as if its modern replacement property name, gap, had been used.
↑ ^11.0 ^11.1 The offset-* properties were renamed inset-* in 11 de martio 2025 by the W3C-CSSWG in the CSS Position 3 module, which supersedes and replaces CSS Logical 1. The 'flow-relative offsets' are now renamed in concordance: inset-block-start, inset-block-end, inset-inline-start, inset-inline-end properties and inset-block, inset-inline e inset shorthands. The deprecated offset-* properties should be distinguished from the still existant offset-* shorthands, offset-anchor, offset-position, offset-path, offset-distance e offset-rotate.
↑ The non-standard property, word-wrap, is also accepted as valid by this extension and is directly aliased to the official property overflow-wrap.
↑ The legacy name alias grid-row-gap is also accepted as valid by this extension and is evaluated exactly as if its modern replacement property name, row-gap, had been used.
↑ ^14.0 ^14.1 Though the creation of the text-align-all property as a constituent value of the text-align shorthand by the W3C-CSSWG took place in 6 de decembre 2018, supporting implementations did not begin appearing until 2025 and, as of the most recent official guidance on 24 de martio 2025, the recommendation to eschew the new property and continue to use the shorthand remains in effect.

How can I target mobile/desktop resolutions?

Media queries allow you to target elements at mobile resolution and desktop resolution. Some advise making your styles mobile friendly by default and wrapping desktop styles within the media query. Note, MediaWiki has standardised on 640px and 1120px breakpoints to represent tablet and desktop.

How can I target specific skins?

MediaWiki provides various classes on the html and body elements, including one that indicates which skin is in use. These can be targeted by including a simple selector for the html or body element including the needed classes, followed by a space (or in CSS terms, the descendant combinator).

Generally, this technique should be used for design consistency, rather than targeting mobile and desktop as all skins can be used in both mobile and desktop resolutions. See also #How can I target mobile/desktop resolutions?.

/* Elements with class foo will have red text in all skins. */
.foo { color: red; }

/* Override that element's color to green for the Vector skin only. */
body.skin-vector .foo { color: green; }

/* Add a red border if the browser doesn't have JavaScript enabled. */
html.client-nojs .foo { border: 1px solid red; }

/* Declare that same border as green for the Vector skin. */
html.client-nojs body.skin-vector .foo { border-color: green; }

/* This does not work; the 'body' element must be selected! */
.skin-vector .foo { background: orange; }

/* These do not work, either; the descendant combinator must be used. */
body.skin-vector > .foo { background: orange; }
body.skin-vector ~ .foo { background: orange; }
html.client-nojs > body.skin-vector .foo { background: orange; }

How do I use styles in MediaWiki messages?

To prevent a malicious user from messing with the parts of the document outside the main content area, all CSS rules automatically get prefixed by the mw-parser-output CSS class. If you use a TemplateStyles-based template outside of the content area (e.g. in the sitenotice ), you need to provide that class yourself, by wrapping the template in something like <div class="mw-parser-output">…</div>.

In which order do CSS styles override?

Which CSS rule takes effect is controlled by specificity (roughly, the complexity of the selector - e.g. div.foo { margin: 10px } is more specific than .foo { margin: 5px }). In case of equal specificity, CSS styles that come later in the document override earlier styles.

MediaWiki:Common.css, other site scripts, user scripts and gadgets are loaded in the ‎<head> section of the page. TemplateStyles stylesheets are loaded in the ‎<body>, so they override site/user script and gadget rules with equal specificity, and in the case of two TemplateStyles rules, the second overrides the first.

Note though that TemplateStyles rules are deduplicated: if the same stylesheet is referenced multiple times on the page, it is only inserted the first time.

Note also that "later" has to do with document position, not load order. Gadgets add their CSS after the page has fully loaded, by manipulating the page with JavaScript; some add it on-demand when the user does some action such as clicking a button. Nevertheless, they add it to the head, so equally-specific CSS rules in the body get precedence over it.

How can Lua modules interact with styles?

TemplateStyles can be called from a Lua module using frame:extensionTag.

Example code is the following:

local p = {};

function p.templateStyle( frame, src )
    return frame:extensionTag( 'templatestyles', '', { src = src } );
end

return p;

What anti-abuse features are provided?

The design choice to store CSS in separate pages was made in part to make integration with the standard anti-abuse toolset easy. TemplateStyles CSS pages have their own content model (sanitized-css) so changes to them can be tracked or controlled with Extension:AbuseFilter , using the new_content_model variable.

CSS inclusion is tracked the same way as template transclusion, so you can see where a stylesheet is used via the "Paginas ligate a iste" option, see what stylesheets are used on a page under "Information sur le pagina" (and possibly on the edit screen, depending on what editor you use), and see what recent changes might be affecting a page using "Modificationes ligate".

TemplateStyles also leaves identifying information in the HTML code; to find out where a specific rule comes from, look at the page source, and the enclosing ‎<style> tag will have an attribute like data-mw-deduplicate="TemplateStyles:r123456", where 123456 is the revision ID of the stylesheet (viewable with Special:Diff, for example).

How were the decisions around TemplateStyles made?

The idea of including CSS with templates was proposed and accepted in a request for comments. Technical details were pinned down in a second RfC and workflow details were expanded through a user consultation.

Who is working on TemplateStyles?

TemplateStyles was originally a project of the Wikimedia Reading Infrastructure team (preceded by exploratory work Coren did as a volunteer), consisting of Brad Jorsch (developer), Bryan Davis (manager) and Gergő Tisza (developer) at the time. People and responsibilities have since moved around; see the maintainers page for current ownership.

Where do I report errors / ask for features?

Please file tasks under the TemplateStyles component in Phabricator.

Where can I see it in action?

You can look at some curated examples.

The feature is enabled on all Wikimedia sites.

Help with errors

background-image

If you receive the following error when trying to publish the changes to your CSS file:

Valor non valide o non supportate pro le proprietate background-image in linea $1 character $2.

It could be that the url('...'); attribute given to background-image is not pointing to a local resource. The parser only allows local resources (and rejects remote ones). Only URLs which point to resources at //upload.wikimedia.org/ are permitted, for example //upload.wikimedia.org/wikipedia/commons/8/83/MediaWiki-2023-button-proposal.svg for the file at File:MediaWiki-2023-button-proposal.svg. These URLs can be obtained by using the URL address that links point to on Wikimedia Commons file pages. These links include those to "Original file" or any of the links to the file's "Other resolutions:" such as 1,024 × 1,024 pixels.