jupyter-book

jupyter-book copied to clipboard

Describe the enhancement you'd like

Wish for a button to toggle between light and dark mode!

Does this solve a specific problem?

Would be nice to have a dark mode/theme or more...

What alternatives exist?

No response

Additional context

https://en.wikipedia.org/wiki/Light-on-dark_color_scheme

This is available in the QuantEcon book theme.

See, for example, https://python-programming.quantecon.org/intro.html (button on top right).

I could preview DARK MODE using Naver's Whale browser. Code blocks and special content blocks are a little less readable, but it is cool.

I wait for the official DARK MODE so that I can use it regardless of what browser I use.

Yes definitely! This change would need to happen in the sphinx-book-theme. We have had an issue about adding a dark mode in that repository for a while, here it is: https://github.com/executablebooks/sphinx-book-theme/issues/265

It is just waiting for a champion to come and try to implement it!

Hi, I am one of the guys who are into the dark mode and I saw: https://sphinx-book-theme.readthedocs.io/en/stable/. It now offers a small icon that enables the switch between light and dark mode. Updating the theme with pip install --upgrade sphinx-book-theme did not bring the switcher icon. So the question is, have any date for the release of the dark/light switcher?

Thank you for the great work

Should this issue now be closed?

Hiya

so iiuc the default output will start in dark mode and offer a button to switch between dark and light

many of my books however don't look that great in dark mode so I'd like to keep the button but start in light mode, how would I go about doing that ?

I was hoping to find this here but no: https://sphinx-book-theme.readthedocs.io/en/stable/reference.html

thanks !

I'd like to keep the button but start in light mode, how would I go about doing that ?

Adding the following to _config.yml works for me:

sphinx:
  html_context:
    default_mode: light

@effigies

thanks for suggesting this approach; however this is not exactly working for me

digging into the code, I could collect the following facts

• every individual html (output by jupyter-book) starts with

  document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
  document.documentElement.dataset.theme = localStorage.getItem("theme") || "light";
  

• and the embedded pydata-sphinx-theme.js has a function setTheme(mode) that once prettified reads

  function setTheme(mode) {
    if (mode !== "light" && mode !== "dark" && mode !== "auto") {
      console.error(`Got invalid theme mode: ${mode}. Resetting to auto.`);
      mode = "auto";
    }
  
    // get the theme
    var colorScheme = prefersDark.matches ? "dark" : "light";
    document.documentElement.dataset.mode = mode;
    var theme = mode == "auto" ? colorScheme : mode;
    document.documentElement.dataset.theme = theme;
  
    // save mode and theme
    localStorage.setItem("mode", mode);
    localStorage.setItem("theme", theme);
    console.log(`[PST]: Changed to ${mode} mode using the ${theme} theme.`);
  
    // add a listener if set on auto
    prefersDark.onchange = mode == "auto" ? autoTheme : "";
  }
  

so my understanding is that if I change the theme on any jb-produced html file, my choice will be remembered in the browser storage, and then apply to any other jb-produced file, even if totally unrelated; is that a correct interpretation ?

If that is correct, it would feel very wrong because imho each document needs to be able to set its preferred mode; not all the stuff written a few years ago is going to look nice in dark mode without some extra curation step...

I just made a few experiments and it very well looks like the conjecture above is right

I understand the need for storing the chosen mode so that one does not have to choose it over and over again while reading along; however it would feel much better if the attributes were somehow namespaced, using e.g. some hash or any other data shared among all the files that are part of the book

not quite sure how to implement this of course at first sight, but from a purely conceptual point of view it would seem the right thing to do imho

I don't think it works for me. I added the suggested configuration and ran

jupyter-book clean --all . && jupyter-book build . 

to be sure everything is reset. In fact, opening my "book" in a private tab, in Firefox, all pages are shown in dark mode.

Interesting. What do you see when you go to https://bids-standard.github.io/stats-models/? I recently updated that with https://github.com/bids-standard/stats-models/pull/82, and using fresh browsers I get light mode even though their system preferences are for dark.

It's all "light" mode :-)

Hi,

Can I ask what the syntax would be in _config.yml to use different logo images in light vs dark mode?

My light mode logo is black which obviously doesn't look good in dark mode. I have a white logo which I'd like to use instead if the user presses the dark mode button.

Its not obvious to me from the config reference -> https://jupyterbook.org/en/stable/customize/config.html

Apologies if this is the wrong place to ask.

Hi,

Can I ask what the syntax would be in _config.yml to use different logo images in light vs dark mode?

My light mode logo is black which obviously doesn't look good in dark mode. I have a white logo which I'd like to use instead if the user presses the dark mode button.

Its not obvious to me from the config reference -> https://jupyterbook.org/en/stable/customize/config.html

Apologies if this is the wrong place to ask.

You can have a section in your _config.yaml that has Sphinx options. Since jupyter book uses pydata sphinx theme, it's the same options as for that theme.

Ex:

sphinx:
  config:
    html_theme_options: 
      logo:
        image_light: YOUR_LIGHT_LOGO.png
        image_dark: YOUR_DARK_LOGO.png

Thanks @janash ! That works for me.

I've done it in conf.py before with sphinx_book_theme but wasn't sure if it was the same in _config.yml.

I don't think it works for me. I added the suggested configuration and ran bash jupyter-book clean --all . && jupyter-book build . to be sure everything is reset. In fact, opening my "book" in a private tab, in Firefox, all pages are shown in dark mode.

So, all seems ok when using, instead of Firefox, the https://wiki.gnome.org/Apps/Web. That is, my interactive manual shows completely in light mode. What's going on with Firefox?

as I tried to explain above, the browser storage is used to store your last choice, so it might explain why 2 browsers behave differently (also, that storage is common to all jb-generated documents, which may create additional confusion)

as I tried to explain above, the browser storage is used to store your last choice, so it might explain why 2 browsers behave differently (also, that storage is common to all jb-generated documents, which may create additional confusion)

Thank you. Indeed, I didn't carefully read your above findings. I note, though, that I explicitly cleaned the cache for the "page" of interest in Firefox. Should I also, really, close and restart Firefox?

how can we disable the dark mode in _config.yml?

Should this be closed as completed? There is one bug with it though: Code blocks collapse does not adapt to the dark theme. This can be seen on the official docs, for example here: https://jupyterbook.org/en/stable/content/layout.html

Screenshot:

Thanks!

It seems like with https://github.com/executablebooks/jupyter-book/issues/1430#issuecomment-1529043746 that the build script does not copy the logo files into the static folder.

https://github.com/executablebooks/jupyter-book/issues/1430#issuecomment-2127569401

@domoritz

It does copy the files under certain circumstances. Here is a simple demo using jupyter book create with a light a dark logo: https://github.com/janash/demo-book . The built book is on the gh-pages branch and the light and dark logos have been copied appropriately (see _static/logo_light.png and _static/logo_dark.png).

I have had issues with the logo copying when I am building the jupyter book from another directory. For example if my repository has a book directory that contains the Jupyter book files and I am doing jupyter book build book (instead of jupyter book build . as for the simple example). It appears to me that the paths in the sphinx section are being interpreted as relative to the directory where the build command is executed, rather than relative to _config.yml as might be expected. I would guess it has to do with the way the jupyter book build commands wraps sphinx build. The behavior seems like a bug, so maybe it warrants another issue.

I see. I have my docs in a subfolder so that is probably it. I fixed it with manually copying the files in https://github.com/cmudig/draco2/blob/fa587cf5dd3603856fb7763cbe50849c51db0807/docs/_config.yml#L54.

I came across this issue trying to find out how to change the default theme to "light". No success with this suggestion by @effigies, which is also mentioned here in the PyData Theme Docs. It works, however, after also setting recursive_update: true:

sphinx:
  recursive_update: true
  config:
    html_context:
      default_mode: light

@parmentelat, not sure if this still relevant for you.

hi @maawoo

thanks for reporting this however, not quite sure exactly how that happened, but somehow this no longer is in my way, in the sense that I don't even have that setting at all, and still I no longer happen to start in dark mode