Documenter.jl
Documenter.jl copied to clipboard
JuliaDocs
Enable user to set default color scheme
I have to admit, while I think the PR https://github.com/JuliaDocs/Documenter.jl/pull/1456 is interesting and useful, I'm not sure it's a great idea by default. I think at least having an optional feature to override the default color-scheme would be beneficial.
For example, many documentation sites are not optimally set-up for dark-theme first (if the user has the OS set to a dark theme).
For example, take a look at https://jump.dev/JuMP.jl
Similarly, the Makie docs look better with a light-default, as the animations and plots use a white background by default
Yes, the recent growth and popularity of DarkMode everywhere has caused a few problems - I've fixed a couple myself and am working through a few more.
The logo at the top left of the Documenter window can automatically switch between light and dark modes. The manual says:
If you want to create a separate design for the dark theme, add a file called logo-dark.svg (or PNG/WEBP/GIF/JPEG).
so that at least can be fixed in an elegant way.
Logos that consist mainly of black-on-transparent-background should probably be redrawn† so that they work better and independently whatever the background color, but it would be even better if Documenter could somehow accept two paths to graphics files and have them automatically selected for display. But this would be terrible for storage space for large documents.
For figures, it's hard to see an alternative to blinding white backgrounds contrasting with dark surroundings. I've been experimenting with off-white colors but I'm not convinced...
Not respecting the user/authors choice also seems wrong... 🤷♂️
† I'm always happy to help 😀
This would need some way to communicate the preference across multiple domains, which, I believe, is not possible with Web Storage which we currently use.
Not respecting the user/authors choice also seems wrong... 🤷♂️
I'm not sure this is really the case or holds true. For example, Github doesn't default to dark mode even thought I have dark mode set to true in my OS level system preferences. There are many examples of website that follow a similar rule.
My preference would be for Documenter.jl to allow package authors enable or disable this auto-detection of OS level dark-mode (still permitting a dark mode toggle).
+1 for that feature! Ideally, there would be a way to have plots adopted to the theme, but as a first (hopefully easy) way, it would be great if it was possible to hard code the theme during the make.
Nonetheless: Massive fan of Documenter.jl!!!
A hack to force the default theme to dark is to add
run(`sed -i'.old' 's/var darkPreference = false/var darkPreference = true/g' docs/build/assets/themeswap.js`)
to the make.jl after the makedocs call. As a result, the user can still manually switch to the light theme, but will, by default, always land on the dark theme regardless their OS setting. But again, this a hack on really not an elegant solution... Thanks to @RoyWiggins for the help!