Allow making non-native site links server-absolute

docs/conf.py

@@ -51,7 +51,12 @@
     # and CI builds https://github.com/pydata/pydata-sphinx-theme/pull/386
     "collapse_navigation": not is_release_build,
     "show_prev_next": False,
-    "native_site": False
+    # Determines the type of links produced in the navigation header:
+    # - absolute: Links point to the URL https://matplotlib.org/...
+    # - server-stable: Links point to top-level of the server /...
+    # - internal: Links point to the internal files as expanded by the `pathto`
+    #   template function in Sphinx.
+    "navbar_links": "absolute",
 }
 
 # Add any paths that contain custom static files (such as style sheets) here,

mpl_sphinx_theme/__init__.py

@@ -8,9 +8,30 @@ def get_html_theme_path():
     return [str(Path(__file__).parent.parent.resolve())]
 
 
+def setup_html_page_context(app, pagename, templatename, context, doctree):
+    """Add a mpl_path template function."""
+    navbar_links = context['theme_navbar_links']
+    if navbar_links not in ['internal', 'absolute', 'server-stable']:
+        raise ValueError(f'Invalid navbar_links theme option: {navbar_links}')
+
+    def mpl_path(path):
+        if navbar_links == 'internal':
+            pathto = context['pathto']
+            return pathto(path)
+        elif navbar_links == 'absolute':
+            return f'https://matplotlib.org/stable/{path}'
+        elif navbar_links == 'server-stable':
+            return f'/stable/{path}'
+        else:
+            raise ValueError(
+                f'Invalid navbar_links theme option: {navbar_links}')
+    context['mpl_path'] = mpl_path
+
+
 # For more details, see:
 # https://www.sphinx-doc.org/en/master/development/theming.html#distribute-your-theme-as-a-python-package
 def setup(app):
     app.add_html_theme("mpl_sphinx_theme",
                        str(Path(__file__).parent.resolve()))
+    app.connect("html-page-context", setup_html_page_context)
     return {'version': __version__, 'parallel_read_safe': True}

mpl_sphinx_theme/mpl_nav_bar.html

@@ -1,49 +1,23 @@
-{% if theme_native_site %}
 <ul id="navbar-main-elements" class="navbar-nav">
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('plot_types/index') }}">Plot types</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('plot_types/index') }}">Plot types</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('gallery/index') }}">Examples</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('gallery/index') }}">Examples</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('tutorials/index') }}">Tutorials</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('tutorials/index') }}">Tutorials</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('api/index') }}">Reference</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('api/index') }}">Reference</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('users/index') }}">User guide</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('users/index') }}">User guide</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('devel/index') }}">Develop</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('devel/index') }}">Develop</a>
   </li>
   <li class="nav-item">
-    <a class="reference internal nav-link" href="{{ pathto('users/release_notes') }}">Release notes</a>
+    <a class="reference internal nav-link" href="{{ mpl_path('users/release_notes') }}">Release notes</a>
   </li>
 </ul>
-{% else %}
-<ul id="navbar-main-elements" class="navbar-nav">
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/plot_types/index">Plot types</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/gallery/index">Examples</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/tutorials/index">Tutorials</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/api/index">Reference</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/users/index">Usage guide</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/devel/index">Develop</a>
-  </li>
-  <li class="nav-item">
-    <a class="reference internal nav-link" href="https://matplotlib.org/stable/users/release_notes">Release notes</a>
-  </li>
-</ul>
-{% endif %}

mpl_sphinx_theme/theme.conf

@@ -3,8 +3,8 @@ inherit = pydata_sphinx_theme
 stylesheet = css/style.css
 
 [options]
-native_site = False
+navbar_links = absolute
 # navbar_start = mpl_navbar_logo.html
 navbar_center = mpl_nav_bar.html
 navbar_end = mpl_icon_links.html, theme-switcher.html
-logo = images/logo2.svg
+logo = images/logo2.svg