Document how themes work

prowlett commented 1 year ago

Theme Customisation: Dark, Pastel, Light

I have a student who prefers to read text on a pink background. The cog at the top has Dark, Pastel, Light. Is it straightforward for me to make her a version with pink background (if I find out the correct pink)?

The documentation says this. Could you write this documentation, or at least give me a hint to get me started?

Adding New Themes. Documentation to be added in the near future.

christianp commented 1 year ago

Our plan is to replace or supplement these buttons with colour selectors, so you can pick exactly the colours you want.

I'll leave this open as a reminder that someone needs to document the themes system.

prowlett commented 1 year ago

Thanks @christianp. I spoke with my student and she confirmed that being able to set chirun pages to pink would be useful so in the short term is there something I can do to help her?

christianp commented 1 year ago

I think this is due a status update: before the last round of strikes, I started work on rewriting the default theme to allow the user to choose their own colours. It needs maybe another day or two of work, but I need to switch back to working on Numbas stuff.

In the short term, I think you can create a themes folder in your Chirun course folder, and put a copy of the default theme there, then make some changes to the CSS. I think you could change the body background-color in static/pastel.css.

prowlett commented 1 year ago

Thanks, this is helpful. I have played around. I didn't want to change the pastel theme because I don't know if other students are using this, so here's what I did.

In my course main folder I made a folder called themes. I copied chirun_env/lib/python3.10/site-packages/chirun/themes/default/ to this folder and changed its name to pink. I edited themes/pink/static/light.css to add the following:

body, .quotation {
    background-color: #ffc0cb;
    color: #425358;
}
.btn-light {
    background-color: #ffc0cb;
    border-color: #ffc0cb;
}

I added the following section to my config.yml:

themes:
  - title: Default
    source: default
    path: default
  - title: Pink
    source: pink
    path: pink

Then when I run chirun I get two folders within build: default and pink.

I made a file at build/index.html with the following content. This is to deal with incoming links from the VLE and people who've bookmarked the old page. This means that people who go to the notes get redirected by default to default/index.html.

<!doctype html>
<html lang="en-GB">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="Refresh" content="0; url='default/index.html'" />
    <title>Module notes</title>
</head>

<body>
    <p>You should be redirected to <a href="default/index.html">the module website</a>.</p>
</body>

</html>

There's nothing at default/index.html that links to the other theme, so I added a link to intro.tex in my main folder like \href{../pink/index.html}{Pink}. This is used in config.yml like this:

- type: introduction
    source: intro.tex
    leading_text: "Welcome to the notes for..."

This file makes a footer below the menus on the homepage (I use it to give my contact details), and now it also has a link "Pink" which goes to the pink theme.

prowlett commented 1 year ago

I am a little concerned about "Our plan is to replace or supplement these buttons with colour selectors, so you can pick exactly the colours you want."

I support this in principle, because I think that users getting configuration options is a good thing. But a problem I think is that we use chirun across a number of modules and the student will access these from multiple devices in different teaching rooms. If it is fiddly, is she going to have a good deal of faff at the start of every class to get this looking how she wants it? Also not all users are comfortable with detailed configuration options. I feel that if I as her educator know what setup she prefers, the best thing would be that I set up my site so that she has a single click to get to a version that is configured how she wants it.

If I could just make a CSS file in my notes site at say themes/pink.css which is another version of light.css, dark.css and pastel.css, and then it finds this and adds 'Pink' to the buttons for 'Light', 'Dark' and 'Pastel', that would seem to be ideal.

This would seem to have several advantages over what I've hacked together above:

I wouldn't have to copy the whole theme and potentially update this if the theme changes.
I wouldn't have to deal with redirecting users to the default theme.
I wouldn't have to upload twice as many files to the VLE each time I add to the notes.
I wouldn't have to deal with giving the user the option to switch to my custom theme.
I could easily say to others running chirun "just make a folder themes and put this file there" and they'd be offering the same option as me.

I would think the best version of this would be if users have the option to set up their own custom config (and potentially save this on their own device) but also if instructors were able to add custom theme switches. The first is anticipatory, the second is a more direct intervention.

christianp commented 8 months ago

The current state of affairs is that the default theme has colour selectors, and settings are saved to local storage so will be used across all Chirun material on the same device. I don't think that having a custom CSS file in each package is the right solution: we'd need every lecturer to do that across all our modules. We do still need to document how themes are supposed to work. At the moment, we're not compiling anything in more than one theme, but we do have a custom theme for the ASK material so it looks like the rest of the ASK site.

chirun-ncl / chirun

Document how themes work #146