#Creating themes

#Quick start

Open this commit. This commit shows you everything you need to do to create a theme for Bibliogram and make it selectable in the settings menu.

https://git.sr.ht/~cadence/bibliogram/commit/7bd43ca857a60a177e0dc3168744fc2c9670fa88

Please use this commit as a reference. For full instructions, read on.

#Understanding what can be themed

• Home page
• Timeline
• Post page

If you want to change a colour that is not available in this list, open an issue about it. I want all foreground colours, background colours, edges of things, and shadows to be editable.

In addition to these colours, you can add any custom CSS to change the appearance of whatever you want.

#Choosing names

First, decide on a display name and a file name for the theme.

The display name will be shown to the public and can be anything.

The file name is not shown the public. It can be anything, but it must be unique forever, so I recommend prefixing it with your screen name to ensure nobody else creates a theme with the same file name. For example, if I wanted to contribute a theme called "midnight", I might name it "cadence_midnight".

Choose a existing theme that you want to base your theme off. If you don't replace a colour value in your theme, then it'll default to the value from the base theme. You should choose the theme that looks the most similar to what you want to create, so that fewer things will break when Bibliogram updates and adds new things that can be themed.

Through the rest of this document, replace {theme_file} with the file name, and {theme_name} with the display name. Read carefully before pasting to make sure you replace all of them. You'll need to replace them in file names and file contents. Do not include the curly braces.

You will also need to replace {base_theme} with the file name of the base theme you chose, for example, classic.

#Setting up

To start, create the file /src/site/sass/{theme_file}.sass with this content:

@use "themes/{theme_file}" as *
@use "includes/main" with ($theme: $theme)

Then, create the file /src/site/sass/themes/_{theme_file}.scss. Notice the underscore _ before {theme_file}! Then, add this content to it:

@use "{base_theme}";
$theme: map-merge({base_theme}.$theme, (
));

#Making your theme selectable

Open /config.js and add this block of code. If you need help, read docs/Configuring.

themes: {
    custom: [
        {file: "{theme_file}", name: "{theme_name}"}
    ],
    default: "{theme_file}"
}

#Changing colours

Add the colour to the .scss file inside the map. For example, after adding a few colours, you might have content like this:

@use "classic";
$theme: map-merge(classic.$theme, (
    "background-power-primary": #3e73b7,
    "background-power-secondary": #274771,
    "background-power-tertiary": #1b233c
));

Syntax notes:

• Use a comma at the end of each line, except for the last line.
• Put quotation marks around the key, but not around the value.
• You can add comments with // or /* */.

#CSS overrides

Add your custom CSS to the bottom of the .scss file if you like the braces syntax, or the .sass file if you like the indented syntax. Note that changes to the .scss come before the main file, and changes to the .sass come after the main file. This may mean that you are only able to overwrite existing styles in the .sass file (or by using !important)

#Applying your changes

Save the file, then reload the page in your browser. That's it! You don't need to restart Bibliogram, the file is automatically compiled and loaded when you save it.

If you don't notice changes, you may have made a syntax error. Check the Bibliogram console for details. If you can't make it work at all, then make sure you used the correct file extensions for the files you created: .sass is not the same as .scss.

#Making a pull request

Have you completed a theme? I'd love to receive a pull request for it to get it into Bibliogram everywhere — the more themes we have, the more fun Bibliogram is! To see how to get your work in Bibliogram, read docs/Submitting a patchset.

Themes are art and they represent your creativity and your personality. As such, I won't be restrictive on what you want to create. The only thing you need to make sure of is accessibility. Make sure that you comply with these:

• There should be at least a 4.5:1 contrast ratio between all text and its background.
• Links should always have an underline and they should have a different colour than the surrounding text.

If your theme is still a work in progress, and you submit a patchset to look for feedback, be sure to let me know that it's a work in progress so that I don't merge it. (Use git send-email --annotate to add comments to your patch, or just send a follow-up to the thread very quickly.)