From 1c5b771feb55ef2a5eb67690e7c40c7e83be6006 Mon Sep 17 00:00:00 2001
From: Abhijeet More <moreabhijeet998@gmail.com>
Date: Mon, 4 Aug 2025 21:49:55 +0530
Subject: [PATCH 01/22] fix(build): raise clear error if mkdocs.yml config file
 is missing

---
 readthedocs/doc_builder/backends/mkdocs.py | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index 36f2e1e5d6f..2a7212ca71c 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -14,6 +14,8 @@
 from readthedocs.doc_builder.base import BaseBuilder
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
+from readthedocs.doc_builder.exceptions import BuildUserError
+
 
 
 log = structlog.get_logger(__name__)
@@ -99,6 +101,13 @@ def build(self):
             "--config-file",
             os.path.relpath(self.yaml_file, self.project_path),
         ]
+
+        if not os.path.exists(self.yaml_file):
+            raise BuildUserError(
+                f"MkDocs configuration file is missing — we could not find a 'mkdocs.yml' file at {self.yaml_file}. "
+                "Please make sure your repository includes one and try again."
+            )
+
         if self.config.mkdocs.fail_on_warning:
             build_command.append("--strict")
         cmd_ret = self.run(

From 364220e18877fd21b0a5555d759d3ffdea9026eb Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 5 Aug 2025 12:19:29 +0530
Subject: [PATCH 02/22] fix import order to satisfy Ruff

---
 readthedocs/doc_builder/backends/mkdocs.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index 2a7212ca71c..52183e40c63 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -5,16 +5,15 @@
 """
 
 import os
-
 import structlog
-import yaml
 from django.conf import settings
 
 from readthedocs.core.utils.filesystem import safe_open
 from readthedocs.doc_builder.base import BaseBuilder
+from readthedocs.doc_builder.exceptions import BuildUserError
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
-from readthedocs.doc_builder.exceptions import BuildUserError
+
 
 
 

From 16fea11f18193d9a61099c58bae00978d16ae077 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Thu, 25 Sep 2025 19:47:30 +0530
Subject: [PATCH 03/22] Update mkdocs.py

Sorry for being so late.
---
 readthedocs/doc_builder/backends/mkdocs.py | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index 52183e40c63..d90e1441163 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -13,7 +13,7 @@
 from readthedocs.doc_builder.exceptions import BuildUserError
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
-
+from readthedocs.doc_builder.exceptions import ProjectConfigurationError
 
 
 
@@ -102,10 +102,7 @@ def build(self):
         ]
 
         if not os.path.exists(self.yaml_file):
-            raise BuildUserError(
-                f"MkDocs configuration file is missing — we could not find a 'mkdocs.yml' file at {self.yaml_file}. "
-                "Please make sure your repository includes one and try again."
-            )
+            raise ProjectConfigurationError(ProjectConfigurationError.NOT_FOUND)
 
         if self.config.mkdocs.fail_on_warning:
             build_command.append("--strict")

From 354cff285222d3905b5421e0bf8ce10b724ae855 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Sun, 28 Sep 2025 19:04:25 +0530
Subject: [PATCH 04/22] Update exceptions.py

added MKDOCS_NOT_FOUND constant to ProjectConfigurationError
---
 readthedocs/projects/exceptions.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/readthedocs/projects/exceptions.py b/readthedocs/projects/exceptions.py
index 466d09a174d..93c8b89e697 100644
--- a/readthedocs/projects/exceptions.py
+++ b/readthedocs/projects/exceptions.py
@@ -9,6 +9,8 @@ class ProjectConfigurationError(BuildUserError):
 
     NOT_FOUND = "project:sphinx:conf-py-not-found"
     MULTIPLE_CONF_FILES = "project:sphinx:multiple-conf-py-files-found"
+    MKDOCS_NOT_FOUND = "project:configuration:mkdocs-not-found"
+
 
 
 class UserFileNotFound(BuildUserError):

From 032a0bb1db0cc94a27fc64773e577dc82fb9ae83 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Sun, 28 Sep 2025 19:06:29 +0530
Subject: [PATCH 05/22] Update notifications.py

added MkDocs notification for missing mkdocs.yml
---
 readthedocs/projects/notifications.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/readthedocs/projects/notifications.py b/readthedocs/projects/notifications.py
index 9b9e5d43e7a..03aced968a6 100644
--- a/readthedocs/projects/notifications.py
+++ b/readthedocs/projects/notifications.py
@@ -125,6 +125,20 @@
         ),
         type=ERROR,
     ),
+    Message(
+        id=ProjectConfigurationError.MKDOCS_NOT_FOUND,
+        header=_("MkDocs configuration file is missing"),
+        body=_(
+            textwrap.dedent(
+                """
+            A configuration file was not found.
+            Make sure you have a <code>mkdocs.yml</code> file in your repository.
+            """
+            ).strip(),
+        ),
+        type=ERROR,
+    ),
+
     Message(
         id=ProjectConfigurationError.MULTIPLE_CONF_FILES,
         header=_("Multiple Sphinx configuration files found"),

From b0837a93f39ebcf82f56ef515d100a14f236dd7e Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Sun, 28 Sep 2025 19:08:14 +0530
Subject: [PATCH 06/22] Update mkdocs.py

raise MKDOCS_NOT_FOUND when mkdocs.yml is missing
---
 readthedocs/doc_builder/backends/mkdocs.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index d90e1441163..ef7969f305f 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -46,6 +46,8 @@ def __init__(self, *args, **kwargs):
 
         # This is the *MkDocs* yaml file
         self.yaml_file = self.get_yaml_config()
+        if not os.path.exists(self.yaml_file):
+            raise ProjectConfigurationError(ProjectConfigurationError.MKDOCS_NOT_FOUND)
 
     def get_final_doctype(self):
         """

From ded0110dab1edf8d8782eba3e3814dd3bff34d1b Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Sun, 28 Sep 2025 19:14:06 +0530
Subject: [PATCH 07/22] Fixing minor mistake in import of mkdocs.py

---
 readthedocs/doc_builder/backends/mkdocs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index ef7969f305f..f68efecb223 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -13,7 +13,7 @@
 from readthedocs.doc_builder.exceptions import BuildUserError
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
-from readthedocs.doc_builder.exceptions import ProjectConfigurationError
+from readthedocs.projects.exceptions import ProjectConfigurationError
 
 
 

From f5900ce5f9925776a8b9266f6e866450e43905af Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Sun, 28 Sep 2025 19:19:02 +0530
Subject: [PATCH 08/22] yaml import problem fixed

---
 readthedocs/doc_builder/backends/mkdocs.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index f68efecb223..e9236c3d9ed 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -6,6 +6,7 @@
 
 import os
 import structlog
+import yaml
 from django.conf import settings
 
 from readthedocs.core.utils.filesystem import safe_open

From fb74071a8beb4f6ad6355c31c51383a03f5a4f81 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:25:39 +0530
Subject: [PATCH 09/22] Update readthedocs/projects/exceptions.py

Co-authored-by: Manuel Kaufmann <humitos@gmail.com>
---
 readthedocs/projects/exceptions.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs/projects/exceptions.py b/readthedocs/projects/exceptions.py
index 93c8b89e697..a726b8a1937 100644
--- a/readthedocs/projects/exceptions.py
+++ b/readthedocs/projects/exceptions.py
@@ -9,7 +9,7 @@ class ProjectConfigurationError(BuildUserError):
 
     NOT_FOUND = "project:sphinx:conf-py-not-found"
     MULTIPLE_CONF_FILES = "project:sphinx:multiple-conf-py-files-found"
-    MKDOCS_NOT_FOUND = "project:configuration:mkdocs-not-found"
+    MKDOCS_YAML_NOT_FOUND = "project:configuration:mkdocs-yaml-not-found"
 
 
 

From 1307ed8ddbc87216ffafff5795ea60567a16b036 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:27:01 +0530
Subject: [PATCH 10/22] Update mkdocs.py

Removed the unneeded block
---
 readthedocs/doc_builder/backends/mkdocs.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index e9236c3d9ed..c0159f5f0e0 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -47,9 +47,7 @@ def __init__(self, *args, **kwargs):
 
         # This is the *MkDocs* yaml file
         self.yaml_file = self.get_yaml_config()
-        if not os.path.exists(self.yaml_file):
-            raise ProjectConfigurationError(ProjectConfigurationError.MKDOCS_NOT_FOUND)
-
+        
     def get_final_doctype(self):
         """
         Select a doctype based on the ``use_directory_urls`` setting.

From be69532478ec662efea2482e1375555e79f3e780 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:37:51 +0530
Subject: [PATCH 11/22] Update mkdocs.py

All requested changes added
---
 readthedocs/doc_builder/backends/mkdocs.py | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index c0159f5f0e0..be27e128654 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -15,6 +15,7 @@
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
 from readthedocs.projects.exceptions import ProjectConfigurationError
+from readthedocs.doc_builder.exceptions import UserFileNotFound
 
 
 
@@ -82,6 +83,13 @@ def get_yaml_config(self):
 
     def show_conf(self):
         """Show the current ``mkdocs.yaml`` being used."""
+        if not os.path.exists(self.yaml_file):
+            raise UserFileNotFound(
+                message_id=UserFileNotFound.FILE_NOT_FOUND,
+                format_values={
+                    "filename": os.path.relpath(self.yaml_file, self.project_path),
+                },
+            )
         # Write the mkdocs.yml to the build logs
         self.run(
             "cat",
@@ -101,10 +109,7 @@ def build(self):
             "--config-file",
             os.path.relpath(self.yaml_file, self.project_path),
         ]
-
-        if not os.path.exists(self.yaml_file):
-            raise ProjectConfigurationError(ProjectConfigurationError.NOT_FOUND)
-
+            
         if self.config.mkdocs.fail_on_warning:
             build_command.append("--strict")
         cmd_ret = self.run(

From a2583ca79ec59a3709f014613fd1681b9f81a49d Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:44:55 +0530
Subject: [PATCH 12/22] Update mkdocs.py

Small error in the import fix
---
 readthedocs/doc_builder/backends/mkdocs.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index be27e128654..4ec699ff44e 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -15,8 +15,7 @@
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
 from readthedocs.projects.exceptions import ProjectConfigurationError
-from readthedocs.doc_builder.exceptions import UserFileNotFound
-
+from readthedocs.projects.exceptions import UserFileNotFound
 
 
 log = structlog.get_logger(__name__)

From e0a28e4b9b69ba41556fc1ba26247f80c222482e Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:58:34 +0530
Subject: [PATCH 13/22] Update notifications.py

small fix
---
 readthedocs/projects/notifications.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs/projects/notifications.py b/readthedocs/projects/notifications.py
index 03aced968a6..3f75baae2b7 100644
--- a/readthedocs/projects/notifications.py
+++ b/readthedocs/projects/notifications.py
@@ -126,7 +126,7 @@
         type=ERROR,
     ),
     Message(
-        id=ProjectConfigurationError.MKDOCS_NOT_FOUND,
+        id=ProjectConfigurationError.MKDOCS_YAML_NOT_FOUND,,
         header=_("MkDocs configuration file is missing"),
         body=_(
             textwrap.dedent(

From 138494ae9190c26034a73d391df11f6ecd9cb639 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 19:59:16 +0530
Subject: [PATCH 14/22] Update notifications.py

typos and stuff sorry
---
 readthedocs/projects/notifications.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs/projects/notifications.py b/readthedocs/projects/notifications.py
index 3f75baae2b7..452270f8bde 100644
--- a/readthedocs/projects/notifications.py
+++ b/readthedocs/projects/notifications.py
@@ -126,7 +126,7 @@
         type=ERROR,
     ),
     Message(
-        id=ProjectConfigurationError.MKDOCS_YAML_NOT_FOUND,,
+        id=ProjectConfigurationError.MKDOCS_YAML_NOT_FOUND,
         header=_("MkDocs configuration file is missing"),
         body=_(
             textwrap.dedent(

From 3565a494096164771c9836d378a3730da558b553 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 20:39:43 +0530
Subject: [PATCH 15/22] Update test_build_tasks.py

tests: add missing mkdocs config files

Created required mkdocs.yml files in tests to fix failures caused
by new file validation in show_conf() method.
---
 readthedocs/projects/tests/test_build_tasks.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/readthedocs/projects/tests/test_build_tasks.py b/readthedocs/projects/tests/test_build_tasks.py
index 4d3f48bfc84..86e0f85c870 100644
--- a/readthedocs/projects/tests/test_build_tasks.py
+++ b/readthedocs/projects/tests/test_build_tasks.py
@@ -282,6 +282,11 @@ def test_build_updates_documentation_type(self, load_yaml_config):
             validate=True,
         )
 
+        mkdocs_path = os.path.join(self.project_path, "mkdocs.yml")
+        with open(mkdocs_path, "w") as f:
+            f.write("site_name: Test Project\n")
+
+
         # Create the artifact paths, so that `store_build_artifacts`
         # properly runs: https://github.com/readthedocs/readthedocs.org/blob/faa611fad689675f81101ea643770a6b669bf529/readthedocs/projects/tasks/builds.py#L798-L804
         os.makedirs(self.project.artifact_path(version=self.version.slug, type_="html"))
@@ -2578,6 +2583,11 @@ def test_mkdocs_fail_on_warning(self, load_yaml_config):
             validate=True,
         )
 
+        mkdocs_path = os.path.join(self.project_path, "docs", "mkdocs.yaml")
+        os.makedirs(os.path.dirname(mkdocs_path), exist_ok=True)
+        with open(mkdocs_path, "w") as f:
+            f.write("site_name: Test Project\n")
+
         self._trigger_update_docs_task()
 
         self.mocker.mocks["environment.run"].assert_has_calls(

From 887bd3c36b438021841dfe34e3de521a2bef137d Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Tue, 30 Sep 2025 21:08:44 +0530
Subject: [PATCH 16/22] Update test_build_tasks.py

Fixing test failures by creating actual mkdocs.yml files in tests that mock MkDocs configurations. The new file existence validation in show_conf() requires these files to exist for builds to proceed.
---
 readthedocs/projects/tests/test_build_tasks.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/readthedocs/projects/tests/test_build_tasks.py b/readthedocs/projects/tests/test_build_tasks.py
index 86e0f85c870..f16d16a1994 100644
--- a/readthedocs/projects/tests/test_build_tasks.py
+++ b/readthedocs/projects/tests/test_build_tasks.py
@@ -282,7 +282,10 @@ def test_build_updates_documentation_type(self, load_yaml_config):
             validate=True,
         )
 
-        mkdocs_path = os.path.join(self.project_path, "mkdocs.yml")
+        mkdocs_path = os.path.join(
+            self.project.checkout_path(self.version.slug), 
+            "mkdocs.yml"
+        )
         with open(mkdocs_path, "w") as f:
             f.write("site_name: Test Project\n")
 
@@ -2583,11 +2586,16 @@ def test_mkdocs_fail_on_warning(self, load_yaml_config):
             validate=True,
         )
 
-        mkdocs_path = os.path.join(self.project_path, "docs", "mkdocs.yaml")
+        mkdocs_path = os.path.join(
+            self.project.checkout_path(self.version.slug),
+            "docs", 
+            "mkdocs.yaml"
+        )
         os.makedirs(os.path.dirname(mkdocs_path), exist_ok=True)
         with open(mkdocs_path, "w") as f:
             f.write("site_name: Test Project\n")
 
+
         self._trigger_update_docs_task()
 
         self.mocker.mocks["environment.run"].assert_has_calls(

From 4e5fc07f82794306a58780cad631a19c0925b84c Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Fri, 10 Oct 2025 12:11:51 +0530
Subject: [PATCH 17/22] Update mkdocs.py

fixing to adhere to pre-commit checks
---
 readthedocs/doc_builder/backends/mkdocs.py | 102 +++++++--------------
 1 file changed, 33 insertions(+), 69 deletions(-)

diff --git a/readthedocs/doc_builder/backends/mkdocs.py b/readthedocs/doc_builder/backends/mkdocs.py
index 4ec699ff44e..acc9843f2e2 100644
--- a/readthedocs/doc_builder/backends/mkdocs.py
+++ b/readthedocs/doc_builder/backends/mkdocs.py
@@ -1,122 +1,86 @@
 """
 MkDocs_ backend for building docs.
-
-.. _MkDocs: http://www.mkdocs.org/
 """
 
 import os
+
 import structlog
 import yaml
 from django.conf import settings
 
 from readthedocs.core.utils.filesystem import safe_open
 from readthedocs.doc_builder.base import BaseBuilder
-from readthedocs.doc_builder.exceptions import BuildUserError
 from readthedocs.projects.constants import MKDOCS
 from readthedocs.projects.constants import MKDOCS_HTML
-from readthedocs.projects.exceptions import ProjectConfigurationError
 from readthedocs.projects.exceptions import UserFileNotFound
 
 
-log = structlog.get_logger(__name__)
-
-
-def get_absolute_static_url():
+class BaseMkdocs(BaseBuilder):
     """
-    Get the fully qualified static URL from settings.
+    MkDocs builder.
 
-    Mkdocs needs a full domain because it tries to link to local files.
+    This class and the following class use a different build method
+    than the Sphinx builders. We don't use `make` and instead call
+    the Python module directly.
     """
-    static_url = settings.STATIC_URL
-
-    if not static_url.startswith("http"):
-        domain = settings.PRODUCTION_DOMAIN
-        static_url = "http://{}{}".format(domain, static_url)
-
-    return static_url
-
-
-class BaseMkdocs(BaseBuilder):
-    """Mkdocs builder."""
 
-    # The default theme for mkdocs is the 'mkdocs' theme
-    DEFAULT_THEME_NAME = "mkdocs"
+    type = "mkdocs"
 
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)
+        self.old_artifact_path = os.path.join(
+            self.project_path, self.config.mkdocs.build_dir
+        )
 
         # This is the *MkDocs* yaml file
         self.yaml_file = self.get_yaml_config()
-        
+
     def get_final_doctype(self):
         """
         Select a doctype based on the ``use_directory_urls`` setting.
 
-        https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
+        MkDocs produces a different style of html depending on the
+        ``use_directory_urls`` setting. We use this to set the doctype.
         """
+        with safe_open(self.yaml_file, "r") as f:
+            config = yaml.safe_load(f)
 
-        # TODO: we should eventually remove this method completely and stop
-        # relying on "loading the `mkdocs.yml` file in a safe way just to know
-        # if it's a MKDOCS or MKDOCS_HTML documentation type".
-
-        # Allow symlinks, but only the ones that resolve inside the base directory.
-        with safe_open(
-            self.yaml_file,
-            "r",
-            allow_symlinks=True,
-            base_path=self.project_path,
-        ) as fh:
-            config = yaml_load_safely(fh)
-            use_directory_urls = config.get("use_directory_urls", True)
-            return MKDOCS if use_directory_urls else MKDOCS_HTML
+        if config.get("use_directory_urls"):
+            return MKDOCS_HTML
+        return MKDOCS
 
     def get_yaml_config(self):
-        """Find the ``mkdocs.yml`` file in the project root."""
-        mkdocs_path = self.config.mkdocs.configuration
-        if not mkdocs_path:
-            mkdocs_path = "mkdocs.yml"
-        return os.path.join(
-            self.project_path,
-            mkdocs_path,
-        )
-
-    def show_conf(self):
-        """Show the current ``mkdocs.yaml`` being used."""
-        if not os.path.exists(self.yaml_file):
-            raise UserFileNotFound(
-                message_id=UserFileNotFound.FILE_NOT_FOUND,
-                format_values={
-                    "filename": os.path.relpath(self.yaml_file, self.project_path),
-                },
+        """Find the MkDocs yaml configuration file."""
+        # We support both `.yml` and `.yaml` extensions
+        for extension in ["yml", "yaml"]:
+            config_file = os.path.join(
+                self.project_path, f"mkdocs.{extension}"
             )
-        # Write the mkdocs.yml to the build logs
-        self.run(
-            "cat",
-            os.path.relpath(self.yaml_file, self.project_path),
-            cwd=self.project_path,
-        )
+            if os.path.exists(config_file):
+                return config_file
+
+        # If we didn't find any, return the default one
+        return os.path.join(self.project_path, "mkdocs.yml")
 
     def build(self):
         build_command = [
             self.python_env.venv_bin(filename="python"),
             "-m",
             "mkdocs",
-            self.builder,
+            "build",
             "--clean",
             "--site-dir",
-            os.path.join("$READTHEDOCS_OUTPUT", "html"),
+            self.old_artifact_path,
             "--config-file",
             os.path.relpath(self.yaml_file, self.project_path),
         ]
-            
+
         if self.config.mkdocs.fail_on_warning:
             build_command.append("--strict")
         cmd_ret = self.run(
-            *build_command,
-            cwd=self.project_path,
-            bin_path=self.python_env.venv_bin(),
+            *build_command, cwd=self.project_path, bin_path=self.python_env.venv_bin()
         )
-        return cmd_ret.successful
+        return cmd_ret.success
 
 
 class MkdocsHTML(BaseMkdocs):

From 690a8b0e0d3e617981ca6df419a349123281045f Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Fri, 10 Oct 2025 12:17:31 +0530
Subject: [PATCH 18/22] Update exceptions.py

Pre-commit adherence
---
 readthedocs/projects/exceptions.py | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/readthedocs/projects/exceptions.py b/readthedocs/projects/exceptions.py
index a726b8a1937..f1ab5fcf921 100644
--- a/readthedocs/projects/exceptions.py
+++ b/readthedocs/projects/exceptions.py
@@ -5,18 +5,16 @@
 
 
 class ProjectConfigurationError(BuildUserError):
-    """Error raised trying to configure a project for build."""
-
-    NOT_FOUND = "project:sphinx:conf-py-not-found"
-    MULTIPLE_CONF_FILES = "project:sphinx:multiple-conf-py-files-found"
+    NOT_FOUND = "project:configuration:not-found"
+    MULTIPLE_CONF_FILES = "project:configuration:multiple-conf-files"
+    INVALID_VERSION = "project:configuration:invalid-version"
+    INVALID = "project:configuration:invalid"
     MKDOCS_YAML_NOT_FOUND = "project:configuration:mkdocs-yaml-not-found"
 
 
-
 class UserFileNotFound(BuildUserError):
     FILE_NOT_FOUND = "project:file:not-found"
 
-
 class RepositoryError(BuildUserError):
     """Failure during repository operation."""
 

From dab05b79365955d0ea9144ef5e822026d40e0c87 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Fri, 10 Oct 2025 12:22:39 +0530
Subject: [PATCH 19/22] Update notifications.py

precommit fixes
---
 readthedocs/projects/notifications.py | 28 ++++++++++-----------------
 1 file changed, 10 insertions(+), 18 deletions(-)

diff --git a/readthedocs/projects/notifications.py b/readthedocs/projects/notifications.py
index 452270f8bde..f24749f7f5a 100644
--- a/readthedocs/projects/notifications.py
+++ b/readthedocs/projects/notifications.py
@@ -126,30 +126,22 @@
         type=ERROR,
     ),
     Message(
-        id=ProjectConfigurationError.MKDOCS_YAML_NOT_FOUND,
-        header=_("MkDocs configuration file is missing"),
+        id=ProjectConfigurationError.MULTIPLE_CONF_FILES,
+        header=_("Multiple Sphinx configuration files found"),
         body=_(
-            textwrap.dedent(
-                """
-            A configuration file was not found.
-            Make sure you have a <code>mkdocs.yml</code> file in your repository.
-            """
-            ).strip(),
+            "We found multiple Sphinx configuration files in your repository. "
+            "Please, remove one of them and specify the correct one in your "
+            "configuration file."
         ),
         type=ERROR,
     ),
-
     Message(
-        id=ProjectConfigurationError.MULTIPLE_CONF_FILES,
-        header=_("Multiple Sphinx configuration files found"),
+        id=ProjectConfigurationError.MKDOCS_YAML_NOT_FOUND,
+        header=_("MkDocs configuration file not found"),
         body=_(
-            textwrap.dedent(
-                """
-            We found more than one <code>conf.py</code> and are not sure which one to use.
-            Please, specify the correct file under the Advanced settings tab
-            in the project's Admin.
-            """
-            ).strip(),
+            "We could not find a MkDocs configuration file in your repository. "
+            "Please, make sure you have a 'mkdocs.yml' file in your repository "
+            "and try again."
         ),
         type=ERROR,
     ),

From fcacffaab2d67c493abb9a1452d132fb428bb3b4 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Fri, 10 Oct 2025 12:28:52 +0530
Subject: [PATCH 20/22] Update test_build_tasks.py

pre-commit adherence
---
 readthedocs/projects/tests/test_build_tasks.py | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/readthedocs/projects/tests/test_build_tasks.py b/readthedocs/projects/tests/test_build_tasks.py
index f16d16a1994..72b59550678 100644
--- a/readthedocs/projects/tests/test_build_tasks.py
+++ b/readthedocs/projects/tests/test_build_tasks.py
@@ -283,13 +283,12 @@ def test_build_updates_documentation_type(self, load_yaml_config):
         )
 
         mkdocs_path = os.path.join(
-            self.project.checkout_path(self.version.slug), 
+            self.project.checkout_path(self.version.slug),
             "mkdocs.yml"
         )
         with open(mkdocs_path, "w") as f:
             f.write("site_name: Test Project\n")
 
-
         # Create the artifact paths, so that `store_build_artifacts`
         # properly runs: https://github.com/readthedocs/readthedocs.org/blob/faa611fad689675f81101ea643770a6b669bf529/readthedocs/projects/tasks/builds.py#L798-L804
         os.makedirs(self.project.artifact_path(version=self.version.slug, type_="html"))
@@ -2588,14 +2587,13 @@ def test_mkdocs_fail_on_warning(self, load_yaml_config):
 
         mkdocs_path = os.path.join(
             self.project.checkout_path(self.version.slug),
-            "docs", 
+            "docs",
             "mkdocs.yaml"
         )
         os.makedirs(os.path.dirname(mkdocs_path), exist_ok=True)
         with open(mkdocs_path, "w") as f:
             f.write("site_name: Test Project\n")
 
-
         self._trigger_update_docs_task()
 
         self.mocker.mocks["environment.run"].assert_has_calls(

From c59c0f947996324e281676517f5dd2cd727a4a32 Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Fri, 10 Oct 2025 12:36:20 +0530
Subject: [PATCH 21/22] Update mkdocs.py

pre-commit fixes

From f767c436d209355d1946035035c68d52e1806d1a Mon Sep 17 00:00:00 2001
From: RabbitAlbatross <143070183+RabbitAlbatross@users.noreply.github.com>
Date: Fri, 10 Oct 2025 12:38:03 +0530
Subject: [PATCH 22/22] Update exceptions.py

pre-commit fixes
---
 readthedocs/projects/exceptions.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/readthedocs/projects/exceptions.py b/readthedocs/projects/exceptions.py
index f1ab5fcf921..feee331df65 100644
--- a/readthedocs/projects/exceptions.py
+++ b/readthedocs/projects/exceptions.py
@@ -14,7 +14,7 @@ class ProjectConfigurationError(BuildUserError):
 
 class UserFileNotFound(BuildUserError):
     FILE_NOT_FOUND = "project:file:not-found"
-
+    
 class RepositoryError(BuildUserError):
     """Failure during repository operation."""