[PATCH RFC] Documentation: typography refresh

[PATCH RFC] Documentation: typography refresh

[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:

  * 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/20231102123225.32768-1-bagasdotme@gmail.com/

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 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

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 12de52a2b17e78..f5713cd70cc17c 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -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,
diff --git a/Documentation/sphinx-static/typography.css b/Documentation/sphinx-static/typography.css
new file mode 100644
index 00000000000000..c3d16186aca4a7
--- /dev/null
+++ b/Documentation/sphinx-static/typography.css
@@ -0,0 +1,62 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+
+:root {
+	/* Font stack inspired by https://www.mediawiki.org/wiki/Typography_refresh */
+	--font-family-sans: sans-serif;
+	--font-family-serif: "Linux Libertine", Georgia, Times, "Source Serif Pro", serif;
+	--font-family-monospace: monospace;
+}
+
+body {
+	font-family: var(--font-family-sans);
+}
+
+div.body {
+	color: #252525;
+}
+
+div.sphinxsidebar h3,
+div.sphinxsidebar h4,
+div.sphinxsidebar input {
+	font-family: var(--font-family-sans);
+}
+
+div.admonition p.admonition-title {
+	font-family: var(--font-family-sans);
+}
+
+span.menuselection {
+	font-family: var(--font-family-sans);
+	/*
+	 * Distinguish menu text from regular prose by giving it
+	 * the same background color as inline pre-formatted text.
+	 */
+	background-color: #ecf0f3;
+}
+
+div.body h1,
+div.body h2 {
+	font-family: var(--font-family-serif);
+}
+
+div.body h3,
+div.body h4,
+div.body h5,
+div.body h6 {
+	font-family: var(--font-family-sans);
+}
+
+code,
+kbd,
+pre,
+samp,
+tt,
+span.pre {
+	font-family: var(--font-family-monospace);
+	/*
+	 * Bump monospace font-size as default (100%) is constrastingly
+	 * too small (10.8px compared to 16px) in certain fonts
+	 * (e.g. DejaVu Sans Mono).
+	 */
+	font-size: 110%;
+}

base-commit: d3f825032091fc14c7d5e34bcd54317ae4246903
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH RFC] Documentation: typography refresh

[Randy Dunlap]

Hi Bagas,

On 6/18/25 9:23 PM, Bagas Sanjaya wrote:
> 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

More readability is debatable IMO.

> 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.)



> 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/20231102123225.32768-1-bagasdotme@gmail.com/
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  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.

-- 
~Randy

Re: [PATCH RFC] Documentation: typography refresh

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 2033 bytes --]

On Thu, Jun 19, 2025 at 12:12:38AM -0700, Randy Dunlap wrote:
> Hi Bagas,
> 
> On 6/18/25 9:23 PM, Bagas Sanjaya wrote:
> > 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.

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).

> 
> 
> 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.)

> 
> 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.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH RFC] Documentation: typography refresh

[Vegard Nossum]

On 19/06/2025 06:23, Bagas Sanjaya wrote:
> 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.

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

Re: [PATCH RFC] Documentation: typography refresh

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 305 bytes --]

On Sun, Jun 22, 2025 at 10:58:08AM +0200, Vegard Nossum wrote:
> 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

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH RFC] Documentation: typography refresh

[Carlos Bilbao]

Hello,

On 6/22/25 22:41, Bagas Sanjaya wrote:
> On Sun, Jun 22, 2025 at 10:58:08AM +0200, Vegard Nossum wrote:
>> 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:

Nacked-by: Carlos Bilbao <carlos.bilbao@kernel.org>

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

Thanks,
Carlos

Re: [PATCH RFC] Documentation: typography refresh

[Bagas Sanjaya]

On 6/25/25 05:59, Carlos Bilbao wrote:
> 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).

> 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 <carlos.bilbao@kernel.org>
> 
> 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.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH RFC] Documentation: typography refresh

[Jonathan Corbet]

Carlos Bilbao <carlos.bilbao.osdev@gmail.com> writes:

> 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

Re: [PATCH RFC] Documentation: typography refresh

[Carlos Bilbao]

Hello,

On 7/3/25 18:50, Jonathan Corbet wrote:
> Carlos Bilbao <carlos.bilbao.osdev@gmail.com> writes:
>
>> 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!


>
> Thanks,
>
> jon


Carlos

Re: [PATCH RFC] Documentation: typography refresh

[Mauro Carvalho Chehab]

Em Thu, 19 Jun 2025 11:23:19 +0700
Bagas Sanjaya <bagasdotme@gmail.com> escreveu:

> 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/20231102123225.32768-1-bagasdotme@gmail.com/
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  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
> 
> diff --git a/Documentation/conf.py b/Documentation/conf.py
> index 12de52a2b17e78..f5713cd70cc17c 100644
> --- a/Documentation/conf.py
> +++ b/Documentation/conf.py
> @@ -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)

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

Re: [PATCH RFC] Documentation: typography refresh

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> 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?

> 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

Re: [PATCH RFC] Documentation: typography refresh

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1707 bytes --]

On Wed, Jun 25, 2025 at 12:46:16PM -0600, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
> 
> > 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.

> 
> > 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...?

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

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]