Automatic light/dark theme change in documentation

General Usage
,
1

I find that some packages (e.g., DifferentialEquations.jl) have documentations that change their themes automatically between light/dark depending on day/night, whereas other packages (e.g., HartreeFockBogoliubov.jl) don’t. I’ve kept these two types of documentations open in the same web browser (Safari) in the same computer (macOS Monterey), and verified that the theme of one documentation changes automatically and and the other doesn’t.

I created the documentation of my own package, and its theme is static. How do I enable automatic theme change in the documentation? This issue in Documenter.jl seems relevant, but it doesn’t describe how to enable the behavior.

2

It turned out that my docs/Project.toml’s [compat] section was specifying the Documenter version of 0.24. Once I increased the version specification to 0.27 (which is the up-to-date version), the documentation locally generated in docs/build/ by julia make.jl started honoring my macOS system preference for the light/dark mode!

However, even if I push this change to GitHub, the documentation deployed to GitHub pages doesn’t honor my macOS system preference for the light/dark mode. I find that the HTML page source of the locally generated documentation is different from the documentation deployed to the GitHub pages. The locally generated documentation starts with

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>Home · SellmeierFit.jl</title>
    <link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/>
    <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.0/css/fontawesome.min.css" rel="stylesheet" type="text/css"/>
    ...

whereas the documentation deployed to the GitHub pages starts with

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
    <title>Home · SellmeierFit.jl</title>
    <script data-outdated-warner src="assets/warner.js"></script>
    <link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/>
    <link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.039/juliamono-regular.css" rel="stylesheet" type="text/css"/>
    ...

If I can enforce the HTML page source of the deployed documentation to be the same as that of the locally generated documentation, the problem might be solved, but I am not sure how to achieve that. Any suggestions?

The GitHub repository of my package is here.

3

A somewhat related observation: I found that when I’ve once manually selected the dark or light theme for a documentation there is no easy way to get back to automatic switching based on my MacOS mode. I guess I’d need to delete the cache or so but that’s just annoyingly inconvenient.

2 Likes
4

@carstenbauer, thanks! I loaded the documentation deployed in the GitHub pages in Safari’s private mode (where the browser history and cache are clean), and verified that the system preference’s light/dark mode was honored. So, I emptied the Safari cache, but the problem persisted. Then, I cleared the Safari history, and the problem was finally solved!

5

Glad that my comment helped you figure out the issue. For reference, I created an issue over at the Documenter.jl repo in which I suggest to add an “auto” option besides the light/dark theme options.

1 Like