From 1e1f0d28a13a906e4bfa576ca72f24e7777f278e Mon Sep 17 00:00:00 2001
From: Bill Little <bill.james.little@gmail.com>
Date: Mon, 9 Feb 2026 12:44:49 +0000
Subject: [PATCH] docs: add `:user:` extlinks convenience

---
 docs/src/common_links.inc                           |  1 +
 docs/src/conf.py                                    |  1 +
 .../documenting/whats_new_contributions.rst         | 13 +++++++++++++
 docs/src/whatsnew/latest.rst                        |  3 +++
 4 files changed, 18 insertions(+)

diff --git a/docs/src/common_links.inc b/docs/src/common_links.inc
index a516332aaf..247372cc10 100644
--- a/docs/src/common_links.inc
+++ b/docs/src/common_links.inc
@@ -47,6 +47,7 @@
 .. _iris-esmf-regrid: https://github.com/SciTools-incubator/iris-esmf-regrid
 .. _netCDF4: https://github.com/Unidata/netcdf4-python
 .. _SciTools Contributor's License Agreement (CLA): https://cla-assistant.io/SciTools/
+.. _extlinks: https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 
 
 .. comment
diff --git a/docs/src/conf.py b/docs/src/conf.py
index 4669b423fd..8f45de51c5 100644
--- a/docs/src/conf.py
+++ b/docs/src/conf.py
@@ -288,6 +288,7 @@ def _dotv(version):
         "https://github.com/SciTools/iris/discussions/%s",
         "Discussion #%s",
     ),
+    "user": ("https://github.com/%s", "@%s"),
 }
 
 # -- Doctest ("make doctest")--------------------------------------------------
diff --git a/docs/src/developers_guide/documenting/whats_new_contributions.rst b/docs/src/developers_guide/documenting/whats_new_contributions.rst
index 82569e57a0..a6b7d13148 100644
--- a/docs/src/developers_guide/documenting/whats_new_contributions.rst
+++ b/docs/src/developers_guide/documenting/whats_new_contributions.rst
@@ -82,6 +82,18 @@ The required content, in order, is as follows:
 
     .. _@tkknight: https://github.com/tkknight
 
+  .. hint::
+
+    Alternatively adopt the ``:user:`` `extlinks`_ convenience instead.
+
+    For example to reference the ``github`` user ``tkknight`` simply use
+    :literal:`:user:\`tkknight\``.
+
+    This will be rendered as :user:`tkknight`.
+
+    In addition, there is now no need to add a full reference to the user within
+    the documentation.
+
 * A succinct summary of the new/changed behaviour.
 
 * Context to the change. Possible examples include: what this fixes, why
@@ -143,3 +155,4 @@ users.  To achieve this several categories may be used.
 **💼 Internal**
   Changes to any internal or development related topics, such as testing,
   environment dependencies etc.
+
diff --git a/docs/src/whatsnew/latest.rst b/docs/src/whatsnew/latest.rst
index 5ad52f4787..7ee91f046e 100644
--- a/docs/src/whatsnew/latest.rst
+++ b/docs/src/whatsnew/latest.rst
@@ -88,6 +88,9 @@ This document explains the changes made to Iris for this release
 
 #. `@tkknight`_ added a gallery carousel to the documentation homepage. (:pull:`6884`)
 
+#. :user:`bjlittle` added the ``:user:`` `extlinks`_ ``github`` user convenience.
+   (:pull:`6931`)
+
 
 💼 Internal
 ===========