diff --git a/docs/source/changelog.md b/docs/source/changelog.md
index 184bb865..e29b1805 100644
--- a/docs/source/changelog.md
+++ b/docs/source/changelog.md
@@ -13,12 +13,8 @@
 #### Breaking changes
 
 - The new config `slug_scheme` defaults to `safe` (recommended) instead of the
-  legacy mode `escape`.
-
-  This will change how
-
-  To opt-out you can configure `slug_scheme` to be
-  `"escape"`.
+  legacy mode `escape`. More deetails on upgrading are available at
+  {ref}`templates:upgrading-from-less-than-7`.
 
   ([#744](https://github.com/jupyterhub/kubespawner/pull/744))
 
diff --git a/docs/source/templates.md b/docs/source/templates.md
index b41c807a..9615f9a9 100644
--- a/docs/source/templates.md
+++ b/docs/source/templates.md
@@ -82,6 +82,8 @@ c.KubeSpawner.remember_pvc_name = False
 This handling isn't general for PVCs, only specifically the default `pvc_name`.
 If you have defined your own volumes, you need to handle changes to these yourself.
 
+(templates:upgrading-from-less-than-7)=
+
 ## Upgrading from kubespawner \< 7
 
 Prior to kubespawner 7, an escaping scheme was used that ensured values were _unique_,