Theming

From Support Wiki
Jump to navigation Jump to search

Theming refers to the general process of making a wiki look more stylized than the default MediaWiki skin. There are several components to theming a wiki, and we can help you with some or all of them, but most wikis are able to do at least some of them themselves.

The first step is to upload a logo. Go to Special:Upload and upload a file called Site-logo.png. Usually this should be a square, but depending on where you want to position it, some other dimensions can work too.

Uploading a favicon

The second step is to upload a favicon. This is the little icon that shows up in a browser tab so that you know what page you're looking at. We encourage doing this ASAP as it makes tracking wikis much easier, especially for the staff who are helping you 😉

  1. Decide on an image. It should look good at very small resolutions.
  2. Go to your favorite .ico converter. https://www.icoconverter.com/ works fine.
  3. Upload your image. Choose 48x48px size.
  4. Go to Special:Upload on your wiki and upload the favicon that you just converted as a file called Site-favicon.ico.
  5. It's normal that the favicon won't render on its file page. You can look at the file page for the support wiki's favicon to see how it looks.
  6. Bypass the cache for your wiki (normally ctrl+F5 or ctrl+shift+R) and check if your favicon is showing in the browser tab.
    • If it is, yay!
    • If not, check if the page :File:Site-favicon.ico does indeed have a file saved at it. You can also ask wiki.gg staff for help at this point.

Troubleshooting

If you think you uploaded your favicon and it's not working, try one of the following:

  • Use cache refresh in your browser (ctrl+F5 or ctrl+shift+R in most browsers).
  • Did you use the right file name? If it's named anything other than File:Site-favicon.ico, then it won't show up.
    • You can use the "move page" function (dropdown menu next to the search bar) to change the name of a file. In this case, type Site-favicon.ico into the box; the "File" part comes from the left side.
    • The file name is case-sensitive, so Site-favicon and Site-Favicon are different. It must be Site-favicon.ico.
  • Is your file actually an ICO file (and not just a renamed file in another format)? Make sure you've used an online converter such as https://www.icoconverter.com/.
  • Does it make sense for your image to show up? E.g., if it's a white image in a light-mode browser tab, or a fully transparent image, it might not show up.

If this list doesn't help you solve the issue, please contact wiki.gg staff in your wiki's onboarding channel.

Uploading a background image

The third step is to upload a background image. Background images are more flexible because they involve some CSS. You may want to have two background images, one for light mode and one for dark mode.

What to title your background image

The names of your background images isn't too important, although most wikis use something like Site-background.jpg and Site-background-dark, or maybe the 2nd one is Site-background-light.jpg if the first one was dark.

What format to use & dimensions

Ideally please use the JPEG format, and dimensions of no more than 2560x1440px. Compress the image using one of the following:

If your image has a very very small palette (2-3 colors total) you may find PNG is smaller; in this case, PNG is fine to use. Please try to keep your background image under 250KB in size, although anything under 500KB should be fine. Some images may be as large as 1MB, but we'd ask you to consider if you really need a site background that detailed.

Attaching the background image to the theme

There are two steps here, first to find the URL and then to copy it to the CSS file. Let's find the URL first:

  1. We first visit the file page that we created. For example, on the support wiki, we use File:Site-background.png.
  2. Click the big thumbnail of the image.
  3. You'll now be at a long(ish) URL like https://support.wiki.gg/images/5/57/Site-background.png.
  4. We care about this part: /images/5/57/Site-background.png. Copy it to your clipboard.

Now it's time to edit the CSS file.

  1. Navigate to MediaWiki:Common.css on your wiki.
  2. Edit the file
  3. Scroll to the right set of variables depending if this is for light or dark theme
  4. Paste this URL inside of the url() for the variable --wiki-body-background-image
  5. If applicable, adjust the other properties. Below is how to set a repeated tile.
/* Configuring a single tile of a repeating background image */
    --wiki-body-background-position: initial;
    --wiki-body-background-size: initial;
    --wiki-body-background-repeat: repeat;
    --wiki-body-background-attachment: fixed; /* your choice, do you want it to scroll with the viewport? */

Customizing the set of themes

We recommend having at least two themes, one light and one dark. But if you really want only one theme, or if you want more than two, you can edit the list at MediaWiki:Theme-definitions .

  • If adding additional themes please remember to specify either |kind=light or |kind=dark, this will make a lot of stuff "just work" and also provide some tagging for the user.
  • The name you list at that page is an internal "key" identifying the theme. You will also have to set a display name for the theme. For example, if you create an entry that says * kittens then you should go to MediaWiki:Theme-kittens and write the display text you want the user to see in the dropdown menu for this theme; in this case, probably you'd write Kittens at that page and nothing else.
  • We do not recommend using the theme-specific MediaWiki pages, since everything should be CSS-variable-based in common.css.

Customizing the accent colors, border colors, etc

Your wiki's MediaWiki:Common.css should have a bunch of documentation on how to customize the variables to be unique to your wiki. You will probably want to learn how to use your browser's dev tools, especially the element inspector, as it will help a lot.

We have a full guide to editing CSS.

Fonts

We have a guide on using Google Fonts. If there's a custom font that you want to use, we require that be licensed freely for commercial use, and in that case we can upload it to our commons wiki and give you an import link.

Creating more than one theme

Let's say you want to have three different dark themes, each with their own background image.

Config

At MediaWiki:Theme-definitions you can write: 

* dark[bundled|kind=dark] <!-- already there -->
* dark2[bundled|kind=dark] <!-- new -->
* dark3[bundled|kind=dark] <!-- new -->

Then Create the page MediaWiki:Theme-dark2 to edit the display name for dark2 (for example, "Midnight") and MediaWiki:Theme-dark3 to set the display name for dark3 (for example, "Deep Ocean").

Styling

Now at MediaWiki:Common.css we can implement the different themes. Since all of them have kind=dark, they will all inherit the variables from the .view-dark block. You can then choose to override only the variables you want to change in a new block below the .view-dark block.

Example: 

:root,
.view-dark {
    /* many variable definitions here */
    /* these will apply to ALL themes with kind=dark */
}

.theme-dark2 {
    /* only override the image here (unless you want to change more things too)
    --wiki-body-background-image: url(/images/9/9b/Wiki-background-dark2.png);
}

.theme-dark3 {
    /* only override the image here (unless you want to change more things too)
    --wiki-body-background-image: url(/images/4/40/Wiki-background-dark3.png);
}

See also

Retrieved from "https://support.wiki.gg/index.php?title=Theming&oldid=5940"