Can we fix images for darkmode?

[graeme-a-stewart]

The tutorial looks pretty bad in dark mode as the images have white backgrounds.

Just adding an alpha channel isn't going to work as the images have black in them, which will become invisible.

I don't know if this easily fixable though as the Jupyterbook website has the same issues. There doesn't seem to be an easy option to force light mode.

[Moelf]

idk if JupyterBook has equivalent of : https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/

[aoanla]

it must support theming by inspection, since looking at the actual HTML source reveals lines like:

<img src="_static/juliaheplogo.png" class="logo__image only-light" alt="Logo image"/>
<script>document.write(`<img src="_static/juliaheplogo.png" class="logo__image only-dark" alt="Logo image"/>`);</script>

so clearly some part of the Sphynx engine behind the scenes knows about the only-light and only-dark css classes...

[aoanla]

https://pydata-sphinx-theme.readthedocs.io/en/latest/user_guide/branding.html is the Sphinx level documentation on this: I'll read it properly in the morning

[cormullion]

For the Documenter sidebar:

There are two main ways you can do this.

One is to make two versions of the logo, one for dark mode (logo_dark.svg|png), one for light mode (logo.svg|png). Documenter will switch between them:

The other way, if you "own" the logo, is to "own" the background as well, ie don't use transparent areas, bring your own background:

This makes life a bit simpler.

In the Documenter content area

Perhaps you don't own the logos, and can't add backgrounds -- you might have to switch between two versions of a logo.
But Documenter doesn't have built-in syntax for the content area, so you'll have to use CSS. Add a file eg extras.css to docs/src/assets/:

.display-light-only {
    display: block;
}

.display-dark-only {
    display: none;
}

.theme--documenter-dark .display-light-only {
    display: none;
}

.theme--documenter-dark .display-dark-only {
    display: block;
}

and include this CSS file into your make.jl file:

format   = Documenter.HTML(
      ...
        assets=["assets/extras.css"],
      ...
        ),

Then you can refer to different images for light and dark modes using the @raw form in your Markdown:

     ```@raw html
          <img class="display-light-only" src="assets/hsf_logo_blue.png" alt="hsf logo"/>
          <img class="display-dark-only" src="assets/hsf_logo_blue_darkbg.png" alt="hsf logo dark mode"/>
     ```