From b9e8d798dfb8f94a07bd96883cc8bd6d60b488cb Mon Sep 17 00:00:00 2001
From: Santos Gallegos <stsewd@proton.me>
Date: Sun, 7 Jan 2024 22:39:07 -0500
Subject: [PATCH] Deprecate canonical_url in favor of html_baseurl (#178)

Rely on html_baseurl for the canonical url instead.
The canonical url is already set in the basic theme

https://github.com/sphinx-doc/sphinx/blob/4e9d1553968653df6699b20afc22b73eb3280185/sphinx/themes/basic/layout.html#L130-L132

That takes into account pages using the dirhtml builder
instead of always adding the `html` extension.
This was introduced in sphinx 1.8.
---
 alabaster/layout.html  | 4 +++-
 docs/customization.rst | 5 ++++-
 2 files changed, 7 insertions(+), 2 deletions(-)

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.