From 0ff8729acd98751cc42bcef9535f5b15acd0d5ee Mon Sep 17 00:00:00 2001
From: Josh Richards <josh.t.richards@gmail.com>
Date: Mon, 1 Sep 2025 09:02:53 -0400
Subject: [PATCH] feat(docs): friendly 404 page

Signed-off-by: Josh Richards <josh.t.richards@gmail.com>
---
 conf.py          | 30 +++++++++++++++++++++++++++++-
 requirements.txt |  1 +
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/conf.py b/conf.py
index 08b572e8b..a649d8cf2 100644
--- a/conf.py
+++ b/conf.py
@@ -10,7 +10,13 @@ now = datetime.datetime.now()
 
 os.environ["READTHEDOCS"] = "True"
 
-extensions = ['sphinx_rtd_theme', 'sphinx_rtd_dark_mode', 'sphinx_copybutton', 'sphinxcontrib.mermaid']
+extensions = [
+    'sphinx_rtd_theme',
+    'sphinx_rtd_dark_mode',
+    'sphinx_copybutton',
+    'sphinxcontrib.mermaid',
+    'notfound.extension',
+]
 
 # General information about the project.
 copyright = str(now.year) + ' Nextcloud GmbH'
@@ -85,3 +91,25 @@ edit_on_github_branch = 'master'
 default_dark_mode = False
 
 latex_engine = "xelatex"
+
+# -- Options for sphinx-notfound-page extension -----------------------------------
+# https://github.com/readthedocs/sphinx-notfound-page
+
+# content context passed to the 404 template
+notfound_context = {
+    "title": "404 Page Not Found",
+    "body": """
+<h1>Page Not Found</h1>
+<h2>Sorry, we can't seem to find the page you're looking for.</h2>
+<h6>Error code: 404</h6>
+
+<h3>Here are some alternatives:</h3>
+<ol>
+  <li>Try using the search box.</li>
+  <li>Check the content menu on the side of this page.</li>
+  <li>Regroup at our <a href="/">documentation homepage.</a></p></li>
+</ol>
+""",
+}
+
+notfound_urls_prefix = None
diff --git a/requirements.txt b/requirements.txt
index 57fd118b6..f3580d4f2 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -27,6 +27,7 @@ sphinxcontrib-htmlhelp==2.1.0
 sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-mermaid==1.0.0
+sphinx-notfound-page
 sphinxcontrib-phpdomain==0.13.1
 sphinxcontrib-qthelp==2.0.0
 sphinxcontrib-serializinghtml==2.0.0