[PATCH] docs: rework footer with semantic markup and responsive layout

[PATCH] docs: rework footer with semantic markup and responsive layout

[Rito Rhymes]

The current Alabaster footer uses a generic `div` container, is
hidden entirely at the theme's small-screen breakpoint, and does
not provide a responsive layout for narrower viewports.

Rework the Alabaster footer to use semantic markup while
preserving its existing content, including the copyright notice,
theme attribution, and Page source link. Structure it with a
responsive flexbox so those items remain visible and orderly on
smaller screens.

Scope the change to Alabaster so other supported themes remain
unaffected.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
---
 Documentation/conf.py                      |  6 ++++
 Documentation/sphinx-static/custom.css     | 25 ++++++++++++++++
 Documentation/sphinx/templates/layout.html | 33 ++++++++++++++++++++++
 3 files changed, 64 insertions(+)
 create mode 100644 Documentation/sphinx/templates/layout.html

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503..7ad1db83e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -432,6 +432,12 @@ if html_theme == "alabaster":
 
 sys.stderr.write("Using %s theme\n" % html_theme)
 
+# Expose the active theme so local templates can avoid overriding
+# theme-specific markup for non-default HTML builds.
+html_context = {
+    "kernel_docs_theme": html_theme,
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..dfe550adf 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -23,6 +23,31 @@ div.document {
     margin: 20px 10px 0 10px;
     width: auto;
 }
+/*
+ * Use a semantic footer that stays visible on small screens and wraps
+ * its content as needed.
+ */
+footer.footer {
+    max-width: 65em;
+    margin: 20px auto 30px auto;
+    padding: 0 15px 0 10px;
+    box-sizing: border-box;
+    font-size: 14px;
+    color: #888;
+}
+
+footer.footer a {
+    color: inherit;
+}
+
+footer.footer div.footer-inner {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.35em 0.6em;
+    text-align: center;
+}
 
 /* Size the logo appropriately */
 img.logo {
diff --git a/Documentation/sphinx/templates/layout.html b/Documentation/sphinx/templates/layout.html
new file mode 100644
index 000000000..52727cabc
--- /dev/null
+++ b/Documentation/sphinx/templates/layout.html
@@ -0,0 +1,33 @@
+{# SPDX-License-Identifier: GPL-2.0 #}
+
+{%- extends "!layout.html" %}
+
+{%- block footer %}
+  {% if kernel_docs_theme == "alabaster" %}
+    <footer class="footer" role="contentinfo">
+      <div class="footer-inner">
+      {% if show_copyright %}
+        <span class="footer-item">&#169;{{ copyright }}.</span>
+      {% endif %}
+      {% if show_sphinx %}
+      {% if show_copyright %}
+        <span class="footer-sep" aria-hidden="true">|</span>
+      {% endif %}
+        <span class="footer-item">
+          Powered by <a href="https://www.sphinx-doc.org/">Sphinx {{ sphinx_version }}</a>
+          &amp; <a href="https://alabaster.readthedocs.io">Alabaster {{ alabaster_version }}</a>
+        </span>
+      {% endif %}
+      {%- if show_source and has_source and sourcename %}
+      {% if show_copyright or show_sphinx %}
+        <span class="footer-sep" aria-hidden="true">|</span>
+      {% endif %}
+        <a class="footer-item" href="{{ pathto('_sources/' + sourcename, resource=True)|e }}"
+           rel="nofollow">{{ _('Page source') }}</a>
+      {%- endif %}
+      </div>
+    </footer>
+  {% else %}
+    {{ super() }}
+  {% endif %}
+{%- endblock %}
-- 
2.51.0

[PATCH v2] docs: rework footer with semantic markup and responsive layout

[Rito Rhymes]

The current Alabaster footer uses a generic `div` container, is
hidden entirely at the theme's small-screen breakpoint, and does
not provide a responsive layout for narrower viewports.

Rework the Alabaster footer to use semantic markup while
preserving its existing content, including the copyright notice,
theme attribution, and Page source link. Structure it with a
responsive flexbox so those items remain visible and orderly on
smaller screens.

Scope the change to Alabaster so other supported themes remain
unaffected.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v2: add Assisted-by attribution

 Documentation/conf.py                      |  6 ++++
 Documentation/sphinx-static/custom.css     | 25 ++++++++++++++++
 Documentation/sphinx/templates/layout.html | 33 ++++++++++++++++++++++
 3 files changed, 64 insertions(+)
 create mode 100644 Documentation/sphinx/templates/layout.html

diff --git a/Documentation/conf.py b/Documentation/conf.py
index 679861503..7ad1db83e 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -432,6 +432,12 @@ if html_theme == "alabaster":
 
 sys.stderr.write("Using %s theme\n" % html_theme)
 
+# Expose the active theme so local templates can avoid overriding
+# theme-specific markup for non-default HTML builds.
+html_context = {
+    "kernel_docs_theme": html_theme,
+}
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..dfe550adf 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -23,6 +23,31 @@ div.document {
     margin: 20px 10px 0 10px;
     width: auto;
 }
+/*
+ * Use a semantic footer that stays visible on small screens and wraps
+ * its content as needed.
+ */
+footer.footer {
+    max-width: 65em;
+    margin: 20px auto 30px auto;
+    padding: 0 15px 0 10px;
+    box-sizing: border-box;
+    font-size: 14px;
+    color: #888;
+}
+
+footer.footer a {
+    color: inherit;
+}
+
+footer.footer div.footer-inner {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.35em 0.6em;
+    text-align: center;
+}
 
 /* Size the logo appropriately */
 img.logo {
diff --git a/Documentation/sphinx/templates/layout.html b/Documentation/sphinx/templates/layout.html
new file mode 100644
index 000000000..52727cabc
--- /dev/null
+++ b/Documentation/sphinx/templates/layout.html
@@ -0,0 +1,33 @@
+{# SPDX-License-Identifier: GPL-2.0 #}
+
+{%- extends "!layout.html" %}
+
+{%- block footer %}
+  {% if kernel_docs_theme == "alabaster" %}
+    <footer class="footer" role="contentinfo">
+      <div class="footer-inner">
+      {% if show_copyright %}
+        <span class="footer-item">&#169;{{ copyright }}.</span>
+      {% endif %}
+      {% if show_sphinx %}
+      {% if show_copyright %}
+        <span class="footer-sep" aria-hidden="true">|</span>
+      {% endif %}
+        <span class="footer-item">
+          Powered by <a href="https://www.sphinx-doc.org/">Sphinx {{ sphinx_version }}</a>
+          &amp; <a href="https://alabaster.readthedocs.io">Alabaster {{ alabaster_version }}</a>
+        </span>
+      {% endif %}
+      {%- if show_source and has_source and sourcename %}
+      {% if show_copyright or show_sphinx %}
+        <span class="footer-sep" aria-hidden="true">|</span>
+      {% endif %}
+        <a class="footer-item" href="{{ pathto('_sources/' + sourcename, resource=True)|e }}"
+           rel="nofollow">{{ _('Page source') }}</a>
+      {%- endif %}
+      </div>
+    </footer>
+  {% else %}
+    {{ super() }}
+  {% endif %}
+{%- endblock %}
-- 
2.51.0

Re: [PATCH v2] docs: rework footer with semantic markup and responsive layout

[Jonathan Corbet]

Rito Rhymes <rito@ritovision.com> writes:

> The current Alabaster footer uses a generic `div` container, is
> hidden entirely at the theme's small-screen breakpoint, and does
> not provide a responsive layout for narrower viewports.
>
> Rework the Alabaster footer to use semantic markup while
> preserving its existing content, including the copyright notice,
> theme attribution, and Page source link. Structure it with a
> responsive flexbox so those items remain visible and orderly on
> smaller screens.
>
> Scope the change to Alabaster so other supported themes remain
> unaffected.
>
> Signed-off-by: Rito Rhymes <rito@ritovision.com>
> Assisted-by: Codex:GPT-5.4
> ---
> v2: add Assisted-by attribution
>
>  Documentation/conf.py                      |  6 ++++
>  Documentation/sphinx-static/custom.css     | 25 ++++++++++++++++
>  Documentation/sphinx/templates/layout.html | 33 ++++++++++++++++++++++
>  3 files changed, 64 insertions(+)
>  create mode 100644 Documentation/sphinx/templates/layout.html

So the footer disappears because there is an explicit display:none in
the Alabaster CSS.  That is indeed a bit weird, I wonder why they would
do that.  That said, why not just override the CSS rather than adding
all of this complexity?

Thanks,

jon

Re: [PATCH v2] docs: rework footer with semantic markup and responsive layout

[Rito Rhymes]

We could use a CSS override if the goal were only to change how
the footer looks. But CSS cannot change the footer's semantics for
accessibility, and that's where a fundamental issue lies.

The default theme renders the footer as a generic `div`, and
`class="footer"` does not give it any semantic meaning. Screen
readers and other accessibility tools do not treat that the same as
a real `<footer>` landmark.

To fix that properly, we need to change the markup, either by
rendering a native `<footer>` element or by adding
`role="contentinfo"` to the existing container. That requires
replacing the footer template/component, not just overriding its CSS.

Since the footer appears on every page, I think it's important to
ensure its a11y-friendly, so it makes sense to fix it at the markup
level rather than just overriding the CSS to be mobile-friendly.

Rito

Re: [PATCH v2] docs: rework footer with semantic markup and responsive layout

[Jonathan Corbet]

"Rito Rhymes" <rito@ritovision.com> writes:

> We could use a CSS override if the goal were only to change how
> the footer looks. But CSS cannot change the footer's semantics for
> accessibility, and that's where a fundamental issue lies.
>
> The default theme renders the footer as a generic `div`, and
> `class="footer"` does not give it any semantic meaning. Screen
> readers and other accessibility tools do not treat that the same as
> a real `<footer>` landmark.
>
> To fix that properly, we need to change the markup, either by
> rendering a native `<footer>` element or by adding
> `role="contentinfo"` to the existing container. That requires
> replacing the footer template/component, not just overriding its CSS.
>
> Since the footer appears on every page, I think it's important to
> ensure its a11y-friendly, so it makes sense to fix it at the markup
> level rather than just overriding the CSS to be mobile-friendly.

Please, include the context you are replying to so people can follow the
discussion.

We are not going to fix Sphinx accessibility piecemeal in this way.  If
that is really the objective, I think the right thing is to work with
the Sphinx project directly and come up with a proper plan for all of
their major elements.  Tweaking the footer - the contents of which will
be read by the screen reader and understood just fine - doesn't really
address that problem.

Thanks,

jon

Re: [PATCH v2] docs: rework footer with semantic markup and responsive layout

[Rito Rhymes]

> We are not going to fix Sphinx accessibility piecemeal in this
> way. If that is really the objective, I think the right thing
> is to work with the Sphinx project directly and come up with a
> proper plan for all of their major elements. Tweaking the
> footer - the contents of which will be read by the screen
> reader and understood just fine - doesn't really address that
> problem.

I see where you're coming from.
In that case, I can reroll this as a CSS-only override for the mobile
rendering issue and drop the markup change.

I agree that the semantic footer question is better handled upstream in
Sphinx rather than piecemeal here.

If that direction works for you, I'll send a reroll accordingly.

Rito

[PATCH v3] docs: restore and reflow footer on narrow screens

[Rito Rhymes]

Alabaster hides the documentation footer below its 65em breakpoint.

Add a local override in custom.css so the footer remains visible on
narrow screens. Adjust its layout to better fit mobile screens without
the sidebar.

Signed-off-by: Rito Rhymes <rito@ritovision.com>
Assisted-by: Codex:GPT-5.4
---
v3: switch to a CSS-only override; no footer replacement

 Documentation/sphinx-static/custom.css | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/Documentation/sphinx-static/custom.css b/Documentation/sphinx-static/custom.css
index db24f4344..397780b39 100644
--- a/Documentation/sphinx-static/custom.css
+++ b/Documentation/sphinx-static/custom.css
@@ -169,3 +169,12 @@ a.manpage {
 	font-weight: bold;
 	font-family: "Courier New", Courier, monospace;
 }
+
+@media screen and (max-width: 65em) {
+    div.footer {
+        display: block;
+        width: auto;
+        margin: 30px 0 0px 0;
+        text-align: center;
+    }
+}
-- 
2.51.0