diff --git a/docs/extensions/html_redirects.py b/docs/extensions/html_redirects.py
index 1614c4372b..52b6a32373 100644
--- a/docs/extensions/html_redirects.py
+++ b/docs/extensions/html_redirects.py
@@ -19,6 +19,10 @@
# Uses redirect_template.html and the list of pages given in
# the file conf.html_redirect_pages
#
+# Redirections can be internal or absolute (i.e., external).
+# - Internal redirects are supplied without quotation marks and must be relative to the document root
+# - External redirects are wrapped in doulbe quotation marks and are used verbatim
+#
# Adapted from ideas in https://tech.signavio.com/2017/managing-sphinx-redirects
import os.path
@@ -53,15 +57,19 @@ def create_redirect_pages(app):
return # only relevant for standalone HTML output
for (old_url, new_url) in app.config.html_redirect_pages:
- print('Creating redirect %s to %s...' % (old_url, new_url))
if old_url.startswith('/'):
print('Stripping leading / from URL in config file...')
old_url = old_url[1:]
-
- new_url = app.builder.get_relative_uri(old_url, new_url)
out_file = app.builder.get_outfilename(old_url)
- print('HTML file %s redirects to relative URL %s' % (out_file, new_url))
+ if new_url.startswith('\"') and new_url.endswith('\"'):
+ # This is an absolute redirect. Slice away the surrouding quotation marks and copy the url verbatim
+ new_url = new_url[1:-1]
+ else:
+ # This is an internal redirect. Find the relative url to the target document
+ new_url = app.builder.get_relative_uri(old_url, new_url)
+
+ print('HTML file %s redirects to URL %s' % (out_file, new_url))
out_dir = os.path.dirname(out_file)
if not os.path.exists(out_dir):
os.makedirs(out_dir)
diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt
index ee05a87ab6..920fc41622 100644
--- a/docs/page_redirects.txt
+++ b/docs/page_redirects.txt
@@ -2,50 +2,55 @@
#
# Space delimited
#
-# New URL should be relative to document root, only)
+# The old URL must be relative to the document root only and MUST NOT contain the file extension
+#
+# The new URL can either be an absolute URL or a relative URL
+# - For absolute URLs, the URL must be wrapped in double quotation marks. Whatever is inside the quotation marks is
+# used verbatim as the URL. Don't forget to add the "http://" or "https://" prefix to your absolute URL.
+# - For relative URLs, must be relative to the document root only and MUST NOT be wrapped with any quotation marks.
#
# Empty lines and lines starting with # are ignored
-api-reference/ethernet/index api-reference/network/index
-api-reference/ethernet/esp_eth api-reference/network/esp_eth
-api-reference/mesh/index api-reference/network/index
-api-reference/mesh/esp_mesh api-reference/network/esp_mesh
-api-reference/peripherals/can api-reference/peripherals/twai
-api-reference/wifi/index api-reference/network/index
-api-reference/wifi/esp_now api-reference/network/esp_now
-api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig
-api-reference/wifi/esp_wifi api-reference/network/esp_wifi
-api-reference/system/tcpip_adapter api-reference/network/esp_netif
-get-started/idf-monitor api-guides/tools/idf-monitor
-get-started-cmake/idf-monitor api-guides/tools/idf-monitor
-get-started/get-started-devkitc hw-reference/esp32/get-started-devkitc
-get-started/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2
-get-started/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit
-get-started/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2
-get-started/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3
-get-started/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
-get-started/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
+api-reference/ethernet/index api-reference/network/index
+api-reference/ethernet/esp_eth api-reference/network/esp_eth
+api-reference/mesh/index api-reference/network/index
+api-reference/mesh/esp_mesh api-reference/network/esp_mesh
+api-reference/peripherals/can api-reference/peripherals/twai
+api-reference/wifi/index api-reference/network/index
+api-reference/wifi/esp_now api-reference/network/esp_now
+api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig
+api-reference/wifi/esp_wifi api-reference/network/esp_wifi
+api-reference/system/tcpip_adapter api-reference/network/esp_netif
+get-started/idf-monitor api-guides/tools/idf-monitor
+get-started-cmake/idf-monitor api-guides/tools/idf-monitor
+get-started/get-started-devkitc hw-reference/esp32/get-started-devkitc
+get-started/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2
+get-started/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit
+get-started/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2
+get-started/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3
+get-started/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
+get-started/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
# The preview 'get-started-cmake' guides are now 'get-started'
-get-started-cmake get-started
-get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile
-get-started-cmake/eclipse-setup get-started/eclipse-setup
-get-started-cmake/establish-serial-connection get-started/establish-serial-connection
-get-started-cmake/index get-started/index
-get-started-cmake/linux-setup get-started/linux-setup
-get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch
-get-started-cmake/macos-setup get-started/macos-setup
-get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch
-get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch
-get-started-cmake/windows-setup get-started/windows-setup
-get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch
-get-started-cmake/get-started-devkitc hw-reference/esp32/get-started-devkitc
-get-started-cmake/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2
-get-started-cmake/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit
-get-started-cmake/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2
-get-started-cmake/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3
-get-started-cmake/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
-get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
+get-started-cmake get-started
+get-started-cmake/add-idf_path-to-profile get-started/add-idf_path-to-profile
+get-started-cmake/eclipse-setup get-started/eclipse-setup
+get-started-cmake/establish-serial-connection get-started/establish-serial-connection
+get-started-cmake/index get-started/index
+get-started-cmake/linux-setup get-started/linux-setup
+get-started-cmake/linux-setup-scratch get-started/linux-setup-scratch
+get-started-cmake/macos-setup get-started/macos-setup
+get-started-cmake/macos-setup-scratch get-started/macos-setup-scratch
+get-started-cmake/toolchain-setup-scratch get-started/toolchain-setup-scratch
+get-started-cmake/windows-setup get-started/windows-setup
+get-started-cmake/windows-setup-scratch get-started/windows-setup-scratch
+get-started-cmake/get-started-devkitc hw-reference/esp32/get-started-devkitc
+get-started-cmake/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2
+get-started-cmake/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit
+get-started-cmake/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2
+get-started-cmake/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3
+get-started-cmake/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
+get-started-cmake/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
api-guides/build-system-cmake api-guides/build-system
api-guides/ulp-cmake api-guides/ulp
@@ -57,15 +62,15 @@ api-reference/network/tcpip_adapter api-reference/network/esp_netif
security/secure-boot security/secure-boot-v1
# Since ESP32-S2, hw-reference URLs are now namespaced by chip
-hw-reference/get-started-devkitc hw-reference/esp32/get-started-devkitc
-hw-reference/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2
-hw-reference/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit
-hw-reference/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2
-hw-reference/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3
-hw-reference/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
-hw-reference/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
-hw-reference/get-started-ethernet-kit-v1.0 hw-reference/esp32/get-started-ethernet-kit-v1.0
-hw-reference/get-started-ethernet-kit hw-reference/esp32/get-started-ethernet-kit
-hw-reference/esp32s2/user-guide-kaluga-1-v1.2 hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit
+hw-reference/get-started-devkitc hw-reference/esp32/get-started-devkitc
+hw-reference/get-started-devkitc-v2 hw-reference/esp32/get-started-devkitc-v2
+hw-reference/get-started-wrover-kit hw-reference/esp32/get-started-wrover-kit
+hw-reference/get-started-wrover-kit-v2 hw-reference/esp32/get-started-wrover-kit-v2
+hw-reference/get-started-wrover-kit-v3 hw-reference/esp32/get-started-wrover-kit-v3
+hw-reference/get-started-pico-kit hw-reference/esp32/get-started-pico-kit
+hw-reference/get-started-pico-kit-v3 hw-reference/esp32/get-started-pico-kit-v3
+hw-reference/get-started-ethernet-kit-v1.0 hw-reference/esp32/get-started-ethernet-kit-v1.0
+hw-reference/get-started-ethernet-kit hw-reference/esp32/get-started-ethernet-kit
+hw-reference/esp32s2/user-guide-kaluga-1-v1.2 hw-reference/esp32s2/user-guide-esp32-s2-kaluga-1-kit
-api-guides/jtag-debugging/configure-wrover api-guides/jtag-debugging/configure-ft2232h-jtag
+api-guides/jtag-debugging/configure-wrover api-guides/jtag-debugging/configure-ft2232h-jtag