Skip to contentSkip to conversation

Documentation: typography refresh

RFC PATCH NAK Bagas Sanjaya 6 participants 12 messages Jun 19, 2025 – Jul 6, 2025 1 message not in the archive Documentation

lore
Share & tools
lore
#0 lore raw

RFC PATCH 1/1 Documentation: typography refresh

At present, kernel documentation uses system serif font for body text. Some people, however, objected to it and instead prefer that the typography choice must be legible, consistent, and accessible (after all, the audience ranges developers peeking into kernel internals to ordinary users that skimmed through Documentation/admin-guide/).

To tackle the problem, follow Wikimedia's typography refresh [1]. For the font choices, instead of using web fonts as in previous attempt [2], use:

* Linux Libertine, Georgia, Times for serif (used in h1 and h2 headings)
* system font for sans-serif and monospace

This allows for more readability and consistency without sacrificing page load times and bandwidth, as the font choices is most likely already available on many platforms.

The reason why serif fonts is used for headings in complement to sans serif in text body is to break up visual monotony of docs page by creating contrast between headings (as entry point to docs information) and text body, which is important considering that kernel docs are quite lengthy with many sections.

For body text (excluding sidebar), it is set to #252525 on top of #FFFFFF background as they have contrast ratio 15.3:1, which is rated as AAA according to WCAG 2.0 section 1.4.6. Having slightly off-black foreground text on white background can reduce eye strain and juxtaposition on dyslexic readers.

This refresh only applies to default Alabaster theme.

[1]: https://www.mediawiki.org/wiki/Typography_refresh
[2]: https://lore.kernel.org/linux-doc/[email protected]/

---
 Documentation/conf.py                      |  5 +-
 Documentation/sphinx-static/typography.css | 62 ++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/sphinx-static/typography.css
Documentation/conf.py +4 -1
index 12de52a2b17e78..f5713cd70cc17c 100644
@@ -310,9 +310,12 @@ if  html_theme == 'alabaster':
         'sidebar_width': '15em',
         'fixed_sidebar': 'true',
         'font_size': 'inherit',
-        'font_family': 'serif',
     }
 
+    html_css_files  = [
+        'typography.css',
+    ]
+
 sys.stderr.write("Using %s theme\n" % html_theme)
 
 # Add any paths that contain custom static files (such as style sheets) here,
Documentation/sphinx-static/typography.css new file +62 -0

62 lines not on this page · raw message

base-commit: d3f825032091fc14c7d5e34bcd54317ae4246903

Signature · 1 line
An old man doll... just what I always wanted! - Clara
reviewer
#1 lore raw

Hi Bagas,

Quoted 10 lines · Bagas Sanjaya

At present, kernel documentation uses system serif font for body text. Some people, however, objected to it and instead prefer that the typography choice must be legible, consistent, and accessible (after all, the audience ranges developers peeking into kernel internals to ordinary users that skimmed through Documentation/admin-guide/).

To tackle the problem, follow Wikimedia's typography refresh [1]. For the font choices, instead of using web fonts as in previous attempt [2], use:

Quoted 5 lines

* Linux Libertine, Georgia, Times for serif (used in h1 and h2 headings)
* system font for sans-serif and monospace

This allows for more readability and consistency without sacrificing

More readability is debatable IMO.

Quoted 8 lines

page load times and bandwidth, as the font choices is most likely already available on many platforms.

The reason why serif fonts is used for headings in complement to sans serif in text body is to break up visual monotony of docs page by creating contrast between headings (as entry point to docs information) and text body, which is important considering that kernel docs are quite lengthy with many sections.

It's interesting that mediawiki chose to split the serif and sans serif usage this way. Newspapers essentially do the opposite: use sans serif for headlines (mostly, not consistently) and use serif for body text.

Have you read "The Psychology of Computer Programming"?
[https://geraldmweinberg.com/Site/Programming_Psychology.html]
The content is very good but (at least in early editions) it was printed completely using a sans serif font (probably Helvetica). It's not a long book and I found the subject very interesting, but it took me forever to read it because it's (or was, don't know about the later editions) in sans serif typeface. I hated that part of it.

So I applied this patch and tested it. It works as far as I can tell. I got tons of sans serif font text instead of serif font text that I don't care for. (I don't mind that the sidebar text is sans serif.)

Quoted 11 lines

For body text (excluding sidebar), it is set to #252525 on top of #FFFFFF background as they have contrast ratio 15.3:1, which is rated as AAA according to WCAG 2.0 section 1.4.6. Having slightly off-black foreground text on white background can reduce eye strain and juxtaposition on dyslexic readers.

This refresh only applies to default Alabaster theme.

[1]: https://www.mediawiki.org/wiki/Typography_refresh
[2]: https://lore.kernel.org/linux-doc/[email protected]/

Quoted 7 lines
---
 Documentation/conf.py                      |  5 +-
 Documentation/sphinx-static/typography.css | 62 ++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/sphinx-static/typography.css

Thanks.

Signature · 1 line
~Randy
#2 lore raw
Quoted 9 lines · Randy Dunlap

Hi Bagas,

Quoted 5 lines · Bagas Sanjaya

The reason why serif fonts is used for headings in complement to sans serif in text body is to break up visual monotony of docs page by creating contrast between headings (as entry point to docs information) and text body, which is important considering that kernel docs are quite lengthy with many sections.

Quoted 3 lines

It's interesting that mediawiki chose to split the serif and sans serif usage this way. Newspapers essentially do the opposite: use sans serif for headlines (mostly, not consistently) and use serif for body text.

IMO I found that sans-serif is more pleasant to eye (i.e. lesser strain) than Times New Roman on screen. My htmldocs build now uses Google Sans Display and Roboto Mono, though (as web fonts).

Quoted 9 lines

Have you read "The Psychology of Computer Programming"?
[https://geraldmweinberg.com/Site/Programming_Psychology.html]
The content is very good but (at least in early editions) it was printed completely using a sans serif font (probably Helvetica). It's not a long book and I found the subject very interesting, but it took me forever to read it because it's (or was, don't know about the later editions) in sans serif typeface. I hated that part of it.

I didn't read it, unfortunately, due to financial constraints. (Oh, and in Indonesia where I live people usually shop things online at Shopee, Tokopedia, and Lazada [my go-to marketplace] instead of Amazon.)

Quoted 4 lines

So I applied this patch and tested it. It works as far as I can tell. I got tons of sans serif font text instead of serif font text that I don't care for. (I don't mind that the sidebar text is sans serif.)

I keep the headings on sidebar in sans-serif. Also, the body text is darkened (but not completely black) to give contrast between docs body and sidebar.

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#3 lore raw
In reply to Bagas Sanjaya
Quoted 10 lines · Bagas Sanjaya

At present, kernel documentation uses system serif font for body text. Some people, however, objected to it and instead prefer that the typography choice must be legible, consistent, and accessible (after all, the audience ranges developers peeking into kernel internals to ordinary users that skimmed through Documentation/admin-guide/).

To tackle the problem, follow Wikimedia's typography refresh [1]. For the font choices, instead of using web fonts as in previous attempt [2], use:

Quoted 7 lines

* Linux Libertine, Georgia, Times for serif (used in h1 and h2 headings)
* system font for sans-serif and monospace

This allows for more readability and consistency without sacrificing page load times and bandwidth, as the font choices is most likely already available on many platforms.

Hi,

Could you share (links to) screenshots of the new look?

I know external links are ephemeral by nature and we prefer to have stuff archived, but I think it would really help everybody to be able to see what you see after applying the patches without having to build it ourselves.

Thanks.

Vegard

#4 lore raw
Quoted 3 lines · Vegard Nossum

Hi,

Could you share (links to) screenshots of the new look?

These are in a tracker issue on my fork [1].

Thanks.

[1]: https://github.com/bagasme/linux/issues/1

Signature · 1 line
An old man doll... just what I always wanted! - Clara
Nacked-by NAK
#5 lore raw

Hello,

Quoted 10 lines · Bagas Sanjaya
Quoted 3 lines · Vegard Nossum

Hi,

Could you share (links to) screenshots of the new look?

These are in a tracker issue on my fork [1].

Thanks.

[1]: https://github.com/bagasme/linux/issues/1

Thanks for the patch and for sharing screenshots, Bagas!

I'll be honest -- I was initially skeptical about the value of changing fonts. But I do see how the updated typography improves readability and feels friendlier overall. It follows modern web design trends like Wikipedia’s; but I do wonder if we’re trading off some of the "personality" of rough/challenging aura that fits kernel dev. Your new version feels a bit less hacky/unique. Anyway, font preferences are subjective, e.g., I've seen people run terminals with white backgrounds!

What I’m more concerned about is that if we merge this, someone else might want to tweak another part of the UX next week simply because it “looks better” to them. We've to draw a line on what kind of UX changes we’re open to. From my side:

Still, I really appreciate the effort you put into this, and I agree that readability matters, especially for long docs like ours.

Thanks,
Carlos

#6 lore raw
Quoted 8 lines · Carlos Bilbao

I'll be honest -- I was initially skeptical about the value of changing fonts. But I do see how the updated typography improves readability and feels friendlier overall. It follows modern web design trends like Wikipedia’s; but I do wonder if we’re trading off some of the "personality" of rough/challenging aura that fits kernel dev. Your new version feels a bit less hacky/unique. Anyway, font preferences are subjective, e.g., I've seen people run terminals with white backgrounds!

I'm also leaning towards following web trends by this font tweak, though.

And yeah, when I first coded my HTML and CSS code in school, my peers would've like to use non-monospace fonts ({sans-}serif) in Windows Notepad without knowing that it was bad idea (as they didn't know that monospace was the norm).

Quoted 10 lines

What I’m more concerned about is that if we merge this, someone else might want to tweak another part of the UX next week simply because it “looks better” to them. We've to draw a line on what kind of UX changes we’re open to. From my side:

Still, I really appreciate the effort you put into this, and I agree that readability matters, especially for long docs like ours.

Any suggestions without this tweak?

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara

A message that is not in the archive (sent off-list or not yet received): CAOc0haLSQVO9RexsMDRJ9zx=TPOi5yC6ADX4VLSbFvi1bhP_iw@mail.gmail.com

maintainer
#8 lore raw
Quoted 2 lines · Carlos Bilbao

Some, we can talk about it, I’d personally like to see a small flag displayed to the left of the language options at the top button.

If I understand you correctly, that's dangerous territory...flags and languages are fraught with all kinds of disagreement and discord. The conventional wisdom is to avoid the use of flags to represent languages.

Thanks,

jon

#9 lore raw

Hello,

Quoted 8 lines · Jonathan Corbet
Quoted 2 lines · Carlos Bilbao

Some, we can talk about it, I’d personally like to see a small flag displayed to the left of the language options at the top button.

If I understand you correctly, that's dangerous territory...flags and languages are fraught with all kinds of disagreement and discord. The conventional wisdom is to avoid the use of flags to represent languages.

Fair, thanks!

Quoted 4 lines

Thanks,

jon

Carlos

#10 lore raw
In reply to Bagas Sanjaya

Em Thu, 19 Jun 2025 11:23:19 +0700
Bagas Sanjaya <[email protected]> escreveu:

Quoted 48 lines

At present, kernel documentation uses system serif font for body text. Some people, however, objected to it and instead prefer that the typography choice must be legible, consistent, and accessible (after all, the audience ranges developers peeking into kernel internals to ordinary users that skimmed through Documentation/admin-guide/).

To tackle the problem, follow Wikimedia's typography refresh [1]. For the font choices, instead of using web fonts as in previous attempt [2], use:

* Linux Libertine, Georgia, Times for serif (used in h1 and h2 headings)
* system font for sans-serif and monospace

This allows for more readability and consistency without sacrificing page load times and bandwidth, as the font choices is most likely already available on many platforms.

The reason why serif fonts is used for headings in complement to sans serif in text body is to break up visual monotony of docs page by creating contrast between headings (as entry point to docs information) and text body, which is important considering that kernel docs are quite lengthy with many sections.

For body text (excluding sidebar), it is set to #252525 on top of #FFFFFF background as they have contrast ratio 15.3:1, which is rated as AAA according to WCAG 2.0 section 1.4.6. Having slightly off-black foreground text on white background can reduce eye strain and juxtaposition on dyslexic readers.

This refresh only applies to default Alabaster theme.

[1]: https://www.mediawiki.org/wiki/Typography_refresh
[2]: https://lore.kernel.org/linux-doc/[email protected]/

---
 Documentation/conf.py                      |  5 +-
 Documentation/sphinx-static/typography.css | 62 ++++++++++++++++++++++
 2 files changed, 66 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/sphinx-static/typography.css
Documentation/conf.py +0 -0
index 12de52a2b17e78..f5713cd70cc17c 100644
@@ -310,9 +310,12 @@ if  html_theme == 'alabaster':
         'sidebar_width': '15em',

Documentation/conf.py if html_theme == 'alabaster': · line 319

Quoted 10 lines
Documentation/conf.py +4 -1
         'fixed_sidebar': 'true',
         'font_size': 'inherit',
-        'font_family': 'serif',
     }
 
+    html_css_files  = [
+        'typography.css',
+    ]
+
 sys.stderr.write("Using %s theme\n" % html_theme)

I liked this part: having fonts inside a css. However the code is broken, as there are already several parts of conf.py which alrease sets html_css_files on different ways, depending on two make vars. From make help:

make DOCS_THEME={sphinx-theme} selects a different Sphinx theme. make DOCS_CSS={a .css file} adds a DOCS_CSS override file for html/epub output.

The code on conf.py in question is:

	if html_theme in ["sphinx_rtd_theme", "sphinx_rtd_dark_mode"]:
		...
	        html_css_files = [
	            "theme_overrides.css",
	        ]
		...
		if html_theme == "sphinx_rtd_theme":
	            # Add color-specific RTD normal mode
            html_css_files.append("theme_rtd_colors.css")
	...
	if "DOCS_CSS" in os.environ:
	    css = os.environ["DOCS_CSS"].split(" ")

	    for l in css:
	        html_css_files.append(l)

You can't just replace html_css_files without considering the above, specially since one could be doing DOCS_CSS="some_other_typography.css".

IMO, the code should be instead:

if html_theme == "alabaster":
if not html_css_files:
html_css_files = [ "typography.css" ]

E.g. only use it if:
- the theme is the default one;
- the Kernel docs will be built without DOCS_CSS.

Thanks,
Mauro

maintainer
#11 lore raw
In reply to Bagas Sanjaya
Quoted 5 lines · Bagas Sanjaya

At present, kernel documentation uses system serif font for body text. Some people, however, objected to it and instead prefer that the typography choice must be legible, consistent, and accessible (after all, the audience ranges developers peeking into kernel internals to ordinary users that skimmed through Documentation/admin-guide/).

So I have not seen the objections from "some people"; can you point to them, please?

Quoted 11 lines

To tackle the problem, follow Wikimedia's typography refresh [1]. For the font choices, instead of using web fonts as in previous attempt [2], use:

* Linux Libertine, Georgia, Times for serif (used in h1 and h2 headings)
* system font for sans-serif and monospace

This allows for more readability and consistency without sacrificing page load times and bandwidth, as the font choices is most likely already available on many platforms.

I am open to style changes to make the docs more readable, but I am far from convinced that this is it. Mixing font styles in that way will not be universally popular, the claim of "more readability" is unsubstantiated, and "consistency" seems out of place when you're making the fonts deliberately inconsistent...?

jon

#12 lore raw
Quoted 10 lines · Jonathan Corbet
Quoted 5 lines · Bagas Sanjaya

At present, kernel documentation uses system serif font for body text. Some people, however, objected to it and instead prefer that the typography choice must be legible, consistent, and accessible (after all, the audience ranges developers peeking into kernel internals to ordinary users that skimmed through Documentation/admin-guide/).

So I have not seen the objections from "some people"; can you point to them, please?

None really but I feel that sans-serif looks aesthetically more pleasant (to my eyes) on screen than bare Times New Roman.

Quoted 13 lines
Quoted 5 lines

To tackle the problem, follow Wikimedia's typography refresh [1]. For the font choices, instead of using web fonts as in previous attempt [2], use:

Quoted 7 lines

* Linux Libertine, Georgia, Times for serif (used in h1 and h2 headings)
* system font for sans-serif and monospace

This allows for more readability and consistency without sacrificing page load times and bandwidth, as the font choices is most likely already available on many platforms.

Quoted 5 lines

I am open to style changes to make the docs more readable, but I am far from convinced that this is it. Mixing font styles in that way will not be universally popular, the claim of "more readability" is unsubstantiated, and "consistency" seems out of place when you're making the fonts deliberately inconsistent...?

Because I don't have anything else to say in my mind as ideas when writing this RFC.

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara