giampaolo · giampaolo · May 2, 2026 · May 2, 2026 · May 2, 2026
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -11,6 +11,7 @@ include README.rst
 include SECURITY.md
 include _bootstrap.py
 include docs/.readthedocs.yaml
+include docs/404.rst
 include docs/DEVNOTES.md
 include docs/Makefile
 include docs/README

diff --git a/docs/404.rst b/docs/404.rst
@@ -0,0 +1,26 @@
+:orphan:
+
+404 - Page not found
+====================
+
+.. code-block:: pytb
+
+   Traceback (most recent call last):
+     File "<browser>", line 1, in <module>
+       fetch_page(url)
+   psutil.NoSuchProcess: process no longer exists (pid=404)
+
+The page you're looking for doesn't exist. Or it does, as a
+:class:`~psutil.ZombieProcess` we can't reap.
+
+What now?
+---------
+
+- Hit ``Ctrl + K`` (or ``⌘ K``) to open the search box.
+- Jump to the :doc:`install guide <install>`, :doc:`API reference <api>`,
+  :doc:`FAQ <faq>` or :doc:`recipes <recipes>`.
+- Read the :doc:`blog <blog>` for posts and release notes.
+- If you got here from a link that *should* work, please
+  `open an issue on GitHub`_.
+
+.. _open an issue on GitHub: https://github.com/giampaolo/psutil/issues/new?title=Broken+link%3A+
diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
@@ -742,6 +742,17 @@ footer div[role="navigation"][aria-label="Footer"] {
     text-decoration-color: currentColor;
 }
 
+/* Easter egg: the © symbol is a link to the 404 page. */
+.footer-text a.footer-egg,
+.footer-text a.footer-egg:visited {
+    color: inherit !important;
+    text-decoration: none !important;
+}
+
+.footer-text a.footer-egg:hover {
+    color: var(--blog-accent) !important;
+}
+
 /* RSS icon anchored to the right of the footer row. Icon-only link,
    so :visited must not change its color (per the theme convention
    for button/icon links). */

diff --git a/docs/_templates/footer.html b/docs/_templates/footer.html
@@ -14,7 +14,7 @@
   {%- block contentinfo %}
     <div class="footer-content">
       <div class="footer-text">
-        <span>&copy; {{ copyright }}</span>
+        <span><a class="footer-egg" href="{{ pathto('404') }}" title="🥚">&copy;</a> {{ copyright }}</span>
         {%- if last_updated %}
         <span>Updated: {{ last_updated }}</span>
         {%- endif %}

diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -14,7 +14,7 @@ Doc improvements (:gh:`2761`, :gh:`2757`, :gh:`2760`, :gh:`2745`, :gh:`2763`,
 :gh:`2764`, :gh:`2767`, :gh:`2768`, :gh:`2769`, :gh:`2771`, :gh:`2774`,
 :gh:`2775`, :gh:`2781`, :gh:`2787`, :gh:`2739`, :gh:`2790`, :gh:`2797`,
 :gh:`2801`, :gh:`2803`, :gh:`2808`, :gh:`2819`, :gh:`2820`, :gh:`2823`,
-:gh:`2828`)
+:gh:`2826, :gh:`2828`, :gh:`2829`)
 
 - Split docs from a single HTML file into multiple new sections:
 
@@ -69,9 +69,8 @@ Doc improvements (:gh:`2761`, :gh:`2757`, :gh:`2760`, :gh:`2745`, :gh:`2763`,
     selected result.
   - Search results are styled as cards with subtle borders and shadows (no
     longer rely on RTD).
-  - :gh:`2826`: identifiers in code blocks (e.g. ``psutil.Process()``,
-    ``p.cpu_percent()``) are now clickable and link to their API reference
-    entry on click, via
+  - Identifiers in code blocks (e.g. ``psutil.Process()``, ``p.cpu_percent()``)
+    are now clickable and link to their API reference entry on click, via
     `sphinx-codeautolink <https://sphinx-codeautolink.readthedocs.io/>`__.
 
 - Testing:
@@ -95,6 +94,8 @@ Doc improvements (:gh:`2761`, :gh:`2757`, :gh:`2760`, :gh:`2745`, :gh:`2763`,
   - All ``.rst`` files are now wrapped to 79 characters via
     https://github.com/giampaolo/rstwrap.
   - Add ``/sitemap.xml`` to help search engine discovery.
+  - Custom 404 page. Hovering over the © copyright in the footer reveals an
+    easter egg. Clicking it takes you to the 404 page containing a joke.
 
 Type hints / enums:
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -45,6 +45,7 @@ def _load(path):
 
 _third_party_exts = [
     "ablog",
+    "notfound.extension",  # custom 404 page
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
@@ -111,6 +112,12 @@ def _load(path):
 # RTD Single Version toggle at the same time.
 html_baseurl = "https://psutil.readthedocs.io/latest/"
 
+#         -------- TODO / IMPORTANT -------
+#
+# sphinx-notfound-page: absolute URL prefix for static files and
+# nav links on 404.html. Will become "/" when we switch domain.
+notfound_urls_prefix = "/latest/"
+
 html_title = PROJECT_NAME
 html_favicon = "_static/images/favicon.svg"
 html_last_updated_fmt = "%Y-%m-%d"  # ISO date shown in the footer

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -2,6 +2,7 @@ ablog==0.11.13
 matplotlib==3.10.8
 sphinx-autobuild
 sphinx-codeautolink==0.18.1
+sphinx-notfound-page==1.1.0
 sphinx-sitemap==2.9.0
 sphinx==9.1.0
 sphinx_copybutton==0.5.2