I wanted to add dark mode support to the default nginx “Welcome to nginx” page. This is about the simplest change I could choose to make - it’s a simple, backwards compatible, small additive change to one single index.html file. My initial version of this change looks like this, and is added to the files <style> element, in the <head> section:
@media (prefers-color-scheme: dark) {
body {
background-color: #363839;
color: #d1cec9;
}
a {
color: #c4c4ff;
}
}So, this is the process of getting that change from my brain, into the upstream nginx codebase.
Checking out the Code & Making the Change
The nginx project uses Mercurial, rather than git for source code control. So you will need Mercurial installed for this. This page has download links & installation info. If you are using Debian/Ubuntu, you can just run this to install it:
$ sudo apt install mercurial
// Once that's done, check to make sure
$ hg --version
Mercurial Distributed SCM (version 5.3.1)
...Once Mercurial is installed, you can check out the source and make the change like this:
// Go to the folder where you want to check out the nginx source
$ cd ~/dev
// Use Mercurial to clone the nginx repo
$ hg clone http://hg.nginx.org/nginx
// Go into the folder
$ cd nginx
// Find the file you need to edit
$ grep -r 'Welcome' .
./docs/html/index.html:<title>Welcome to nginx!</title>
./docs/html/index.html:<h1>Welcome to nginx!</h1>
// Make the change
$ $EDITOR ./docs/html/index.htmlTo test this change, you can just open the ~/dev/nginx/docs/html/index.html in a browser using “File → Open”, as it’s just static HTML.
Contributing the Change Upstream
Nginx development is mailing list based, rather than Github/lab/forge/etc… based. The basic plan is to:
- Join the mailing list
- Send an email to the list, containing a patch with the change.
Follow the instructions here to join the mailing list. You will receive a confirmation email. Once you’ve done that, you can send an email to the list with your change in.
To get your change in a format that’s ready to email, I did this:
// Commit the change and write a changelog
$ hg commit
// Export the change as a patch, ready to email
$ hg export tipThis is the output of that, which I copied & pasted into an email – and sent it to nginx-devel@nginx.org:
# HG changeset patch
# User Duncan Lock <duncan.lock@gmail.com>
# Date 1628952253 25200
# Sat Aug 14 07:44:13 2021 -0700
# Node ID 81294b370e774c792210904f710abc0a494c5c05
# Parent dda421871bc213dd2eb3da0015d6228839323583
Add support for dark color scheme in default index.html page
Add a little CSS to index.html to support dark color schemes.
This will display the index page in dark colors if the user has
requested a dark color scheme in their system UI or browser, and
display the same as the previous version if not.
See: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
diff -r dda421871bc2 -r 81294b370e77 docs/html/index.html
--- a/docs/html/index.html Tue Aug 10 23:43:17 2021 +0300
+++ b/docs/html/index.html Sat Aug 14 07:44:13 2021 -0700
@@ -8,6 +8,15 @@
margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif;
}
+ @media (prefers-color-scheme: dark) {
+ body {
+ background-color: #363839;
+ color: #d1cec9;
+ }
+ a {
+ color: #c4c4ff;
+ }
+ }
</style>
</head>
<body>Back & Forth on the Mailing List
This is my thread on the mailing lists web archive, showing the back & forth discussion which ensued after my initial email.
First Maxim Dounin, one of the nginx core developers, politely said no thanks:
Thank you for the patch. I don’t think this is something we want to customize in the example pages such as index.html, especially given that we don’t set other colors.
My heart sank… but after a while I came back and read it again… “especially given that we don’t set other colors.”. I guess I shouldn’t have hardcoded those dark colors in my change – that’s fair enough. I then started looking to see if there was a way to tell the browser to just use its own built-in stylesheet for the dark-mode colors, just like it does for the regular, light-mode version.
A little while later, Steffan Weber replied with the answer:
You could add the following line which makes modern browsers use colors from their built-in dark color scheme:
<meta name=”color-scheme” content=”light dark”>
Second Try
So, next morning I did some research & testing, then reset my repository to have another go:
$ hg strip tipI then sent in this patch, with Steffan’s suggested change, which did exactly what we wanted:
# HG changeset patch
# User Duncan Lock <duncan.lock@gmail.com>
# Date 1629049097 25200
# Sun Aug 15 10:38:17 2021 -0700
# Node ID 945d9836012ed84dea05577027a30a38e38a59f3
# Parent dda421871bc213dd2eb3da0015d6228839323583
Add support for dark color scheme in default index & 50x pages
Add a meta tag to index.html & 50x.html to support dark color schemes.
This will display the index page in dark colors if the user has
requested a dark color scheme in their system UI or browser, and
display the same as the previous version if not.
This uses the browsers built-in styles and doesn't hard code any colors or styles.
diff -r dda421871bc2 -r 945d9836012e docs/html/50x.html
--- a/docs/html/50x.html Tue Aug 10 23:43:17 2021 +0300
+++ b/docs/html/50x.html Sun Aug 15 10:38:17 2021 -0700
@@ -2,6 +2,7 @@
<html>
<head>
<title>Error</title>
+<meta name="color-scheme" content="light dark">
<style>
body {
width: 35em;
diff -r dda421871bc2 -r 945d9836012e docs/html/index.html
--- a/docs/html/index.html Tue Aug 10 23:43:17 2021 +0300
+++ b/docs/html/index.html Sun Aug 15 10:38:17 2021 -0700
@@ -2,6 +2,7 @@
<html>
<head>
<title>Welcome to nginx!</title>
+<meta name="color-scheme" content="light dark">
<style>
body {
width: 35em;Then Maxim replied saying, essentially, “better, but I’d rather use CSS instead of adding a meta tag” - i.e. remove the meta tag and add this CSS: html { color-scheme: light dark; }.
Maxim also included his patch which implemented this and asked me to test it.
I tested his patch, which worked great and then made a suggestion about removing the hardcoded fonts too, which was declined, sadly.
Done & Released
Maxim then committed his final version of the patch… and that was it!
So, in the end, I didn’t actually get any of my code into nginx, but the process was fairly painless, everyone was polite and helpful – and the nginx welcome & error pages now respect your dark mode preferences. I did at least get my name in the changelog:
Dark mode support in welcome and 50x error pages.
Prodded by Duncan Lock.
This is what the welcome page code looks like now:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>
<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>
<p><em>Thank you for using nginx.</em></p>
</body>
</html>
This got released on Aug 31st 2021, as part of nginx 1.21.2 🎉