Message-ID: <20250619042318.17325-2-bagasdotme@gmail.com>
Date: Thu, 19 Jun 2025 11:23:19 +0700
From: Bagas Sanjaya <bagasdotme@...il.com>
To: Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
	Linux Documentation <linux-doc@...r.kernel.org>
Cc: Jonathan Corbet <corbet@....net>,
	Mauro Carvalho Chehab <mchehab@...nel.org>,
	Federico Vaga <federico.vaga@...a.pv.it>,
	Akira Yokosawa <akiyks@...il.com>,
	Carlos Bilbao <carlos.bilbao@...nel.org>,
	Avadhut Naik <avadhut.naik@....com>,
	Alex Shi <alexs@...nel.org>,
	Yanteng Si <si.yanteng@...ux.dev>,
	Dongliang Mu <dzm91@...t.edu.cn>,
	Thomas Gleixner <tglx@...utronix.de>,
	Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
	Stanislav Fomichev <sdf@...gle.com>,
	David Vernet <void@...ifault.com>,
	Miguel Ojeda <ojeda@...nel.org>,
	James Seo <james@...iv.tech>,
	Daniel Vetter <daniel.vetter@...ll.ch>,
	Bagas Sanjaya <bagasdotme@...il.com>
Subject: [PATCH RFC] 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/20231102123225.32768-1-bagasdotme@gmail.com/

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

Powered by blists - more mailing lists