diff --git a/alabaster/layout.html b/alabaster/layout.html
index c5bcc80..6dc077d 100644
--- a/alabaster/layout.html
+++ b/alabaster/layout.html
@@ -6,7 +6,9 @@
   {% if theme_touch_icon %}
     <link rel="apple-touch-icon" href="{{ pathto('_static/' ~ theme_touch_icon, 1) }}" />
   {% endif %}
-  {% if theme_canonical_url %}
+
+  {# Deprecated in favor of html_baseurl (pageurl). This is already set in the basic theme #}
+  {% if theme_canonical_url and not pageurl %}
     <link rel="canonical" href="{{ theme_canonical_url }}{{ pagename }}.html" />
   {% endif %}
 {% endblock %}
diff --git a/docs/customization.rst b/docs/customization.rst
index fd50d90..fa2a844 100644
--- a/docs/customization.rst
+++ b/docs/customization.rst
@@ -71,12 +71,15 @@ Settings related to text display, logo, etc.
 
 * ``body_text_align``: Which CSS ``text-align`` value to use for body text
   (if there is any.)
-* ``canonical_url``: If set, is used as the base URL (set before the relative
+* ``canonical_url``: **Deprecated**, please use the html_baseurl_ Sphinx option instead.
+  If set, is used as the base URL (set before the relative
   path/pagename) for a ``<link rel="canonical">`` `canonical URL
   <https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls>`_ header tag.
 
   .. note:: This value must end with a trailing slash.
 
+  .. _html_baseurl: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl
+
 * ``description``: Text blurb about your project, to appear under the logo.
 * ``description_font_style``: Which CSS ``font-style`` to use for description
   text.