Skip to content

Hugo docs: Support for dark themes: Invert images to match the theme #6284

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

Conversation

bernhardkaindl
Copy link
Collaborator

@bernhardkaindl bernhardkaindl commented Feb 8, 2025

When I enabled Hugo theme selection (including dark themes) for the new Xapi docs,
we noted that images weren't properly adapted for the dark themes and that we could
fix these later. This PR fixes those minor problems when a dark theme is selected:

  • The docs use SVG images that draw black on transparent background,
    making them black-on-black in the dark themes.
  • Other black-on-white drawings are inverted to white-on-black to match
    the dark theme as well. This is also more friendly to dark theme users.
  • The text in the tables in the XenAPI class and releases pages is not legible.

Addressed by:

  1. The issues with transparent SVGs when the page body is fixed by inverting the images.
    It turns the the black foreground into white foreground on darker backgrounds.
  2. Fix the default Zebra-styled tables now (manual zebra-styling for is no longer needed,
    removing the manual styling fixes makes the tables improves them in light and dark modes)
  3. Tables for the XenAPI class reference use hard-coded shades of grey but do not set the text colour.
    Dark themes, change it from black to white but then the text is not visible against bright gray.
    As it currently does not work to use the grey shades from the theme in this case,
    hard-code the text color to black. This fixes the contrast to keep the text visible.

Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
Signed-off-by: Bernhard Kaindl <bernhard.kaindl@cloud.com>
Copy link
Contributor

@lindig lindig left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To avoid problems in future upgrades I would like to avoid too much gold plating which could haunt us in the future. Let's be realistic: xapi et al is maintained not by a huge community but a small corporate team.

@bernhardkaindl
Copy link
Collaborator Author

bernhardkaindl commented Feb 10, 2025

I'm thankful that this small team created a documentation site that is accessible and
well-maintained and helps newcomers to understand the miracles this software does.

I do think that this documentation is an great asset that is very helpful to understand how the individual parts work.


PS: Here is a preview of the docs with this PR (but the other PRs are not applied):
https://bernhard-xapi-onrender-com-pr-6.onrender.com/xenopsd/architecture/index.html

How this works:

I configured a fork of this repository for automatic Hugo previews on http://render.com using this blueprint: https://github.com/bernhard-xapi/bernhard-xapi.onrender.com/blob/main/render.yaml. After enabling previews for pull requests , I got this preview site created automatically after opening a local PR in the repository. This is the PR showing the creation of the preview site: bernhard-xapi#6 (it only supports local pull requests within the repository, so I had to create a local PR for it)

Copy link
Contributor

@edwintorok edwintorok left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Light/dark can be changed by the 'Auto' button in bottom-left (and seems to have correctly defaulted to 'dark'). I was kind of hoping there'd a built-in way in Hugo to do this though.
Looking at CSS invert does color inversion, which doesn't necessarily preserve contrast differences (and hue-rotate even has a warning that it doesn't). Newer versions of CSS have an oklab and oklch feature for more scientifically correct handling of lightness, but it only takes individual colors into account, not surrounding.
Models such as CIECAM or WCAG3's APCA would take surrounding into effect, but I can't find equivalents of these in CSS.

For now this fixes the immediate problem of images not being visible when in dark mode, but we should keep an eye on developments in upstream Hugo and CSS to simplify this in the future.

@lindig lindig added this pull request to the merge queue Feb 10, 2025
Merged via the queue into xapi-project:master with commit 510a0a3 Feb 10, 2025
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants