Merge pull request #53 from pallets/fix-canonical

fix dirhtml canonical url

CHANGES.rst

@@ -3,6 +3,11 @@ Version 2.0.2
 
 Unreleased
 
+-   Detect if Sphinx dirhtml builder is generating canonical URLs with
+    ".html" and replace with the correct dir URL. :issue:`47`
+-   ``canonical_url`` config is deprecated. Use Sphinx's built-in
+    ``html_baseurl`` config instead. :pr:`53`
+
 
 Version 2.0.1
 -------------

src/pallets_sphinx_themes/__init__.py

@@ -5,7 +5,9 @@
 import textwrap
 from collections import namedtuple
 
+from sphinx.application import Sphinx
 from sphinx.builders._epub_base import EpubBuilder
+from sphinx.builders.dirhtml import DirectoryHTMLBuilder
 from sphinx.builders.singlehtml import SingleFileHTMLBuilder
 from sphinx.errors import ExtensionError
 
@@ -72,19 +74,40 @@ def add_404_page(app):
 
 
 @only_pallets_theme()
-def canonical_url(app, pagename, templatename, context, doctree):
-    """Build the canonical URL for a page. Appends the path for the
-    page to the base URL specified by the
-    ``html_context["canonical_url"]`` config and stores it in
-    ``html_context["page_canonical_url"]``.
+def canonical_url(app: Sphinx, pagename, templatename, context, doctree):
+    """Sphinx 1.8 builds a canonical URL if ``html_baseurl`` config is
+    set. However, it builds a URL ending with ".html" when using the
+    dirhtml builder, which is incorrect. Detect this and generate the
+    correct URL for each page.
+
+    Also accepts the custom, deprecated ``canonical_url`` config as the
+    base URL. This will be removed in version 2.1.
     """
-    base = context.get("canonical_url")
+    base = app.config.html_baseurl
 
-    if not base:
+    if not base and context.get("canonical_url"):
+        import warnings
+
+        warnings.warn(
+            "'canonical_url' config is deprecated and will be removed"
+            " in Pallets-Sphinx-Themes 2.1. Set Sphinx's 'html_baseurl'"
+            " config instead.",
+            DeprecationWarning,
+        )
+        base = context["canonical_url"]
+
+    if (
+        not base
+        or not isinstance(app.builder, DirectoryHTMLBuilder)
+        or not context["pageurl"]
+        or not context["pageurl"].endswith(".html")
+    ):
         return
 
+    # Fix pageurl for dirhtml builder if this version of Sphinx still
+    # generates .html URLs.
     target = app.builder.get_target_uri(pagename)
-    context["page_canonical_url"] = base + target
+    context["pageurl"] = base + target
 
 
 @only_pallets_theme()
@@ -157,7 +180,7 @@ def get_version(name, version_length=2, placeholder="x"):
     version = ".".join(release.split(".", version_length)[:version_length])
 
     if placeholder:
-        version = "{}.{}".format(version, placeholder)
+        version = f"{version}.{placeholder}"
 
     return release, version
 

src/pallets_sphinx_themes/themes/pocoo/layout.html

@@ -5,13 +5,6 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
 {%- endset %}
 
-{% block extrahead %}
-  {%- if page_canonical_url %}
-    <link rel="canonical" href="{{ page_canonical_url }}">
-  {%- endif %}
-  {{ super() }}
-{%- endblock %}
-
 {% block sidebarlogo %}
   {% if pagename != "index" or theme_index_sidebar_logo %}
     {{ super() }}