Help:Styling content

This is a guide on how to best deal with styling wiki content on 'local' wikis. It captures a set of lessons learned by both development teams and English Wikipedia administrators. Specifically, this does NOT deal with adapting the user interface via skins, gadgets and userscripts and core and extension development.

Why is styling so difficult?

There is a multitude of reasons, but much comes down to efficiency. Properly styling content requires knowledge about CSS, wikis, and browsers. Additionally MediaWiki is huge and due to its long history, some things are inconsistent for the sake of backwards compatibility.

Guidelines

• Styling content should be done sparingly, because KISS.
• Styling content should primarily be done using TemplateStyles
• Never make assumptions about the dimensions of a page. Pages are shown in contexts that are super narrow and physically small as well as on super wide monitors.
• You should always design mobile first. Mobile is generally the 'simplest' layout and also the format used by most visitors. Make sure that your content is stacked properly in a narrow column and use media queries. Only after that works, adapt the sizing for wider screen sizes by making use of media queries. See below for media query breakpoints

Anti-patterns

Anti-patterns are things that you should probably avoid. It looks like they works, but sometimes they don't do anything at all, or they negatively influence the ability of other people to make changes

!important

Avoid using !important. Using important makes it harder for other styles to override your choices. And while you may think you have anticipated all ways in which you are 'right', with the vast size of mediawiki it is impossible to consider everything.

In most cases you don't need it at all. In other cases it may be the result of a bug elsewhere in the program. In general, to override a rule you use the same selector as the original style rule. Since CSS cascades, this works naturally (styles applied later override styles applied earlier, selectors don't need to be of higher specificity).

If the overriding styles apply before the original styles, the styles got loaded in the wrong order. That should be addressed, but you may resort to workarounds to artificially increase the specificity:

• Repeat the same selector to increase weight, like .foo.foo.
• Add or repeat attribute selectors, like [class].
• Use default elements as ancestor selector (e.g. body .foo, html body .foo).

Add however many points you need. It will still allow multiple stylesheets to use the same technique and each express their specificity. Better than adding in ancestors classes not related to your code. (And more maintainable as they won't change.)

z-index

Avoid using z-index when possible. Instead, try to use the natural stacking order in the DOM; elements that are later in the DOM will be 'higher'. Definitely don't use high values of z-index. If you need to be higher than another z-index, you go 1 point higher than the z-index of that element and no more.

Useful information

• When skins have a responsive viewport they carry the class mobile on the body element
• Each skin has the class skin-skinname on the body element
• Each page carries several classes on the body element to identify the page a user is on: page-PageName, ns-namespaceid and action-actionname
• sitedir
• contentdir
• Common viewport breakpoints are: