Force external links to open in a new tab

.mailmap

@@ -17,3 +17,4 @@ Sadie Bartholomew <sadie.bartholomew@metoffice.gov.uk>  Sadie L. Bartholomew <30
 Tomek Trzeciak             <tomasz.trzeciak@metoffice.gov.uk>                       <TomekTrzeciak@users.noreply.github.com>
 Tomek Trzeciak             <tomasz.trzeciak@metoffice.gov.uk>   TomekTrzeciak       <tomasz.trzeciak@metoffice.gov.uk>
 Thomas Coleman  <15375218+ColemanTom@users.noreply.github.com>
+Samuel Denton <samuel.denton@metoffice.gov.uk> samuel-denton <samuel.denton@metoffice.gov.uk>

CONTRIBUTING.md

@@ -58,6 +58,7 @@ requests_).
  - Elliot Fontaine
  - Mark Dawson
  - James Frost
+ - Samuel Denton
 <!-- end-shortlog -->
 
 (All contributors are identifiable with email addresses in the git version

src/_static/css/custom.css

@@ -19,3 +19,13 @@
 .logo {
   height: 7em !important;
 }
+
+/* Add an icon to external links, excluding those with the "image-reference" class */
+a.external:not(.image-reference)::after {
+  font-size: 0.7em;
+  font-weight: bolder;
+  margin-left: 0.3em;
+  vertical-align: super;
+  opacity: 0.5;
+  content: "↗";
+}

src/_static/js/extern_links_new_tab.js

@@ -0,0 +1,31 @@
+/* ----------------------------------------------------------------------------
+ * Copyright (C) NIWA & British Crown (Met Office) & Contributors.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * ------------------------------------------------------------------------- */
+
+/*
+    Adds target=_blank to external links so they open in a new tab:
+    - noopener: prevents the new page accessing window.opener (tabnabbing protection)
+    - noreferrer: removes referrer info and adds extra safety
+    - title and aria-label: provide context for screen readers and tooltips
+*/
+document.addEventListener("DOMContentLoaded", function () {
+    document.querySelectorAll('a.external').forEach(link => {
+        link.setAttribute('target', '_blank');
+        link.setAttribute('rel', 'noopener noreferrer');
+        link.setAttribute('title', 'Opens in a new tab.');
+        link.setAttribute('aria-label', 'External link: opens in a new tab');
+    });
+});

src/conf.py

@@ -239,18 +239,29 @@ def generate_task_icon_modifier_rst():
     'sidebar_version_name': None,  # override name in version picker
 }
 
-html_static_path = ['_static']
-
-# These paths are either relative to html_static_path
-# or fully qualified paths (eg. https://...)
-html_css_files = ['css/custom.css']
-
 # Disable timestamp otherwise inserted at bottom of every page.
 html_last_updated_fmt = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'cylcdoc'
 
+# -- Static file locations -----------------------------------------------
+html_static_path = ['_static']
+
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+# NOTE: these are added to the end of the default/theme static files, so
+# will override them if there are any conflicts.
+
+# Custom CSS
+html_css_files = [
+    'css/custom.css',
+]
+
+# Custom JS
+html_js_files = [
+    'js/extern_links_new_tab.js',
+]
 
 # -- Options for LaTeX output ---------------------------------------------