~cadence/bibliogram-docs

5f5f50cecd1641d96a7febf813f067997b703626 — Cadence Ember 3 months ago ce4badf
Add creating themes documentation
1 files changed, 144 insertions(+), 0 deletions(-)

A docs/Creating themes.md
A docs/Creating themes.md => docs/Creating themes.md +144 -0
@@ 0,0 1,144 @@
# 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](https://cadence.moe/i/24a900)
- [Timeline](https://cadence.moe/i/d25411)
- [Post page](https://cadence.moe/i/77e606)

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].

[docs/Configuring]: https://git.sr.ht/~cadence/bibliogram-docs/tree/master/docs/Configuring.md

    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][patchset].

[patchset]: https://git.sr.ht/~cadence/bibliogram-docs/tree/master/docs/Submitting%20a%20patchset.md

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.)