Define a theme through a dedicated configuration file

[Andre601]

This is kind of an extension of #247 about custom stylesheets without CSS, but I wanted to post it as a separate thing since I believe it's not 100% the same.

I have two main ideas I would like to share and explain a bit, so that it hopefully is understood.

Configuration file for custom Styles

Something that can be annoying for custom styles is to actually make and use the CSS files. Not everyone knows the ins and outs of CSS and copying a template CSS from giscus also won't help that much since there will still be the question of what each option is used for and where.

My first idea is to have a separate configuration file, which would allow a more simplified way of configuring a custom style to use.

For example could it be a giscus.yml file inside the .github/ directory, where you can have settings for all the different color schemes, but also settings such as comment ordering and such.

Example file:

colors:
  scheme: 'dark'
  background: '#000'
  text: '#fff'

comments:
  reversed: false
  text-box-position: top # Put at the very top

The difficult part here is obviously, if that could even work, or if a CSS is a requirement. Alternatively could giscus generate a CSS file based on the YML file and use that for styling, but this could cause additional load on the backend I would assume.

Automatic theme selection

Giscus could benefit from an option where the colour scheme is automatically determined by what the user has set in his system preferences, or what his Profile settings are on GitHub while logged in.

When a custom theme would be used would this be ignored, but it could be beneficial in many ways.

[laymonage]

Thanks for the suggestion! It's an interesting idea, though I admit it feels a bit like over-engineering.

copying a template CSS from giscus also won't help that much since there will still be the question of what each option is used for and where.

I'm not sure how a yaml config would solve this problem, to be honest. In the end, you'll have to define most, if not all, the colors. You can't just define some of the colors and rely on some default colors based on the scheme (light/dark), because the other parts might not be legible when combined with those colors. The yaml keys would end up being pretty much the same CSS variables with simplified names.

I think a better approach would be to document the essential CSS variables and users can work out the rest. Defining the variable values is straightforward and pretty much the same as a yaml file once they're documented: https://github.com/giscus/giscus/blob/main/styles/themes/custom_example.css#L38-L85

but also settings such as comment ordering and such.

I'm working on a dedicated option for the comment box in #358. The comments order will be implemented just like on GitHub, e.g.

Other than those, I don't think there will be any other customization (presentation-wise) that's worth putting in a config. Custom CSS will always be an option for those who really need to customize the look.

Also, I think we can reuse giscus.json for configs like these, since the code already supports it. Using yaml would need a yaml parser, which means another dependency. Plus, there are things like the "Norway Problem"...

Giscus could benefit from an option where the colour scheme is automatically determined by what the user has set in his system preferences, or what his Profile settings are on GitHub while logged in.

I would love to have that, but unfortunately GitHub doesn't seem to provide an API to get the user's theme preferences.