From 52587cb962d2d99333deec67626ce3f4526b8c10 Mon Sep 17 00:00:00 2001
From: Elijah Greenstein <elijah.greenstein@canonical.com>
Date: Fri, 29 May 2026 15:28:49 -0700
Subject: [PATCH] doc: update conf.py and add js for URL migration

These changes support migration of the documentation from
documentation.ubuntu.com/microcloud to canonical.com/microcloud/docs:

- Adds `doc/_static/js/overwrite_links.js` to properly handle links in
  the flyout menu (version selector).
- Updates configuration settings in `doc/conf.py`
- Reorganizes JavaScript files into `doc/_static/js` directory, and
  updates relevant paths

Signed-off-by: Elijah Greenstein <elijah.greenstein@canonical.com>
---
 doc/_static/js/overwrite_links.js           | 38 +++++++++++++++++++++
 doc/_static/{ => js}/rtd-versions-flyout.js |  0
 doc/conf.py                                 | 19 ++++++-----
 3 files changed, 48 insertions(+), 9 deletions(-)
 create mode 100644 doc/_static/js/overwrite_links.js
 rename doc/_static/{ => js}/rtd-versions-flyout.js (100%)

diff --git a/doc/_static/js/overwrite_links.js b/doc/_static/js/overwrite_links.js
new file mode 100644
index 000000000..c23cdb11a
--- /dev/null
+++ b/doc/_static/js/overwrite_links.js
@@ -0,0 +1,38 @@
+ // Replace oldDomain with newDomain
+ const oldDomain = 'canonical-microcloud-documentation.readthedocs-hosted.com';
+ const newDomain = 'canonical.com/microcloud/docs';
+
+ function escapeRegExp(value) {
+     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ }
+
+ function overwriteMatchingAnchorUrls(container) {
+     if (!container) return;
+
+     const anchors = container.querySelectorAll('a[href], link[href]');
+     const oldDomainRegex = new RegExp(escapeRegExp(oldDomain), 'g');
+
+     anchors.forEach(anchor => {
+         anchor.href = anchor.href.replace(oldDomainRegex, newDomain);
+     });
+ }
+
+ overwriteMatchingAnchorUrls(document.querySelector('header'));
+
+ // Use a MutationObserver to wait for the RTD flyout element to appear in the DOM
+ const observer = new MutationObserver(function(mutations, obs) {
+
+     const rtdFlyout = document.querySelector('readthedocs-flyout');
+     if (!rtdFlyout) return;
+
+     obs.disconnect();
+
+     rtdFlyout.addEventListener('click', function() {
+         const shadowRoot = rtdFlyout.shadowRoot;
+         if (!shadowRoot) return;
+
+         overwriteMatchingAnchorUrls(shadowRoot);
+     });
+ });
+
+ observer.observe(document.body, { childList: true, subtree: true });
diff --git a/doc/_static/rtd-versions-flyout.js b/doc/_static/js/rtd-versions-flyout.js
similarity index 100%
rename from doc/_static/rtd-versions-flyout.js
rename to doc/_static/js/rtd-versions-flyout.js
diff --git a/doc/conf.py b/doc/conf.py
index 170772fc2..6d46aa9ef 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -32,14 +32,18 @@
 # Copyright string; shown at the bottom of the page
 copyright = '2014-%s AGPL-3.0, %s' % (datetime.date.today().year, author)
 
-# Use RTD canonical URL to ensure duplicate pages have a single canonical URL
-# that includes the version (such as /latest/); helps SEO.
-html_baseurl = os.environ.get('READTHEDOCS_CANONICAL_URL', '/')
+# Documentation website URL
+
+version_slug = f'{os.environ.get("READTHEDOCS_VERSION", "local")}'
+
+slug = 'microcloud/docs'
+
+html_baseurl = f'https://canonical.com/microcloud/docs/{version_slug}/'
 
 # OpenGraph metadata used for social sharing previews
 ogp_site_url = html_baseurl
 ogp_site_name = html_title
-ogp_image = 'https://documentation.ubuntu.com/microcloud/latest/_static/microcloud_tag.png'
+ogp_image = f'https://canonical.com/microcloud/docs/{version_slug}/_static/microcloud_tag.png'
 
 html_favicon = '_static/favicon.png'
 
@@ -77,10 +81,6 @@
     'source_edit_link': html_context['github_url']
 }
 
-# Project slug
-# Required if your project is hosted on documentation.ubuntu.com
-slug = 'microcloud'
-
 #######################
 # Sitemap configuration: https://sphinx-sitemap.readthedocs.io/
 #######################
@@ -207,7 +207,8 @@
 
 html_js_files = [
     'https://assets.ubuntu.com/v1/287a5e8f-bundle.js',
-    'rtd-versions-flyout.js',
+    'js/rtd-versions-flyout.js',
+    "js/overwrite_links.js",
 ]
 
 # Feedback button at the top; enabled by default