How to contribute a theme to Tildes

Want to contribute a theme to Tildes but don't know where to start? Let's fix that.

Before we start, get yourself a development environment setup and do a quick read through of the general development info to get acquainted with how Tildes works (or at least the HTML and CSS section).

For this walkthrough I'll be using tildexample as the example name for the theme, but if you decide to contribute a theme for real, make sure it uses the proper name of your theme. :P

Step 1: Sassy _Sass

Open the Tildes codebase using your text editor of choice and navigate to the themes directory at tildes/scss/themes. Then create a copy of _default.scss at _tildexample.scss. The default White theme is the canonical source of all colors used, so it's the best place to start from.

Below is an annotated example of all the things you need to change in your new theme file.

// Add a small description of the theme here with maybe a link to its website.
// Check the other themes for examples. https://example.org/tildexample

// Change the theme variable to $theme-tildexample
// ↓ ↓ ↓ ↓ ↓ ↓ 
$default-theme: (
  // A whole bunch of color definitions, edit as your theme demands.
  // ...
);

// Append ".theme-tildexample" to the body selector.
// ↓ ↙
body {
  // Don't forget to update the theme variable here too.
  //                  ↓ ↓ ↓ ↓ ↓ ↓ ↓
  @include use-theme($default-theme);
}

@include theme-preview-block(
  // Change the text to tildexample.
  // ↓ ↓
  "white",
  // And again update the theme variable here.
  //       ↓ ↓ ↓ ↓ ↓ ↓ ↓
  map-get($default-theme, "foreground-primary"),
  map-get($default-theme, "background-primary")
  //       ↑ ↑ ↑ ↑ ↑ ↑ ↑
);

Once that's done, head to tildes/scss/styles.scss and at the bottom of the file add your theme import:

@import "themes/tildexample";

Step 2: Hardcoding a TheMe coLor

Boy that title is a stretch just to say, we need to add 2 lines to the HTML base template.

Inside the tildes/tildes/templates/base.jinja2 file is a section of if/elif/elif/elif/... statements to set the theme color meta element. Add yourself an elif block and add your theme color.

For this you probably want to use the background-primary color you used in your theme definition. I've used #ff00dd below because it spells food. I'm such a jokester.

{% elif request.current_theme == "tildexample" %}
<meta name="theme-color" content="#ff00dd">
{% endif %}

Step 3: Snakey Wakey

Finally the last step is to grab your trusty pungi and give it a blow.

Head to tildes/tildes/views/settings.py and find the THEME_OPTIONS constant. Here you want to add the theme class you used in body.theme-<this part> and a proper name that will be shown in the theme dropdown.

THEME_OPTIONS = {
    "white": "White",
    # Many other themes...
    "tildexample": "Tildes Theme Example",
}

Once that's all been done, check it out in your development site and see if it works.

Now git!

Commit. Push. Merge request. Have some water. Deimos reviews, merges and deploys your theme. Job's done.