Documentation: typography refresh
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
@@ -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
Randy Dunlap
reviewerHi 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 monospaceThis 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
Signed-off-by Bagas Sanjaya <[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
Thanks.
Signature · 1 line
~Randy
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
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 monospaceThis 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
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
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.
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
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:
Nacked-by Carlos Bilbao <[email protected]>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
Jonathan Corbet
maintainerQuoted 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
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
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 monospaceThis 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]/Signed-off-by Bagas Sanjaya <[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.cssDocumentation/conf.py +0
-0@@ -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
Jonathan Corbet
maintainerQuoted 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 monospaceThis 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
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 monospaceThis 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