diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index d9222bb..948cbaa 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -13,6 +13,7 @@ version: 2
 
 mkdocs:
   configuration: mkdocs.yml
+  fail_on_warning: true
 
 # Optionally declare the Python requirements required to build your docs
 python:
diff --git a/mkdocs.yml b/mkdocs.yml
index 2a5a12e..7c80e9c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,4 +1,17 @@
 site_name: Basic MkDocs Example Project
+
+# This setting is required for Canonical URLs.
+# You can read more about why you should consider using this:
+# https://docs.readthedocs.io/en/stable/canonical-urls.html
+#
+# Until https://github.com/readthedocs/readthedocs.org/issues/9781 is fixed,
+# you need to define CUSTOM_CANONICAL_URL yourself as a workaround.
+#
+# For instance, navigate to Admin => Environment and define
+# CUSTOM_CANONICAL_URL=https://SLUG.readthedocs.io/en/stable/
+# (don't expose it to PRs, they publish on different URLs)
+site_url: !ENV CUSTOM_CANONICAL_URL
+
 theme:
   name: readthedocs
   highlightjs: true