Documentation for #7827

docs/reference/contrib/redirects.rst

@@ -40,6 +40,35 @@ Page model recipe of to have redirects created automatically when changing a pag
 
 For an editor's guide to the interface, see :ref:`managing_redirects`.
 
+Automatic redirect creation
+===========================
+
+.. versionadded:: 2.16
+
+Wagtail automatically creates permanent redirects for pages (and their descendants) when they are moved or their slug is changed. This helps to preserve SEO rankings of pages over time, and helps site visitors get to the right place when using bookmarks or using outdated links.
+
+Creating redirects for alternative page routes
+----------------------------------------------
+
+If your project uses ``RoutablePageMixin`` to create pages with alternative routes, you might want to consider overriding the ``get_route_paths()`` method for those page types. Adding popular route paths to this list will result in the creation of additional redirects; helping visitors to alternative routes to get to the right place also.
+
+For more information, please see :meth:`~wagtail.core.models.Page.get_route_paths`.
+
+Disabling automatic redirect creation
+-------------------------------------
+
+Wagtail's default implementation works best for small-to-medium sized projects (5000 pages or fewer) that mostly use Wagtail's built-in methods for URL generation.
+
+Overrides to the following ``Page`` methods are respected when generating redirects, but use of specific page fields in those overrides will trigger additional database queries.
+
+* :meth:`~wagtail.core.models.Page.get_url_parts()`
+* :meth:`~wagtail.core.models.Page.get_route_paths()`
+
+If you find the feature is not a good fit for your project, you can disable it by adding the following to your project settings:
+
+.. code-block:: python
+
+  WAGTAILREDIRECTS_AUTO_CREATE = False
 
 Management commands
 ===================

docs/reference/pages/model_reference.rst

@@ -269,6 +269,8 @@ In addition to the model fields provided, ``Page`` has many properties and metho
 
     .. automethod:: can_move_to
 
+    .. automethod:: get_route_paths
+
     .. attribute:: password_required_template
 
         Defines which template file should be used to render the login form for Protected pages using this model. This overrides the default, defined using ``PASSWORD_REQUIRED_TEMPLATE`` in your settings. See :ref:`private_pages`

docs/reference/signals.rst

@@ -127,6 +127,16 @@ The best way to distinguish between a 'move' and 'reorder' is to compare the ``u
     # Register a receiver
     pre_page_move.connect(clear_old_page_urls_from_cache)
 
+``page_slug_changed``
+---------------------
+
+This signal is emitted from a ``Page`` when a change to its slug is published.
+
+The following arguments are emitted by this signal:
+
+:sender: The page ``class``.
+:instance: The updated (and saved), specific ``Page`` instance.
+:instance_before: A copy of the specific ``Page`` instance from **before** the changes were saved.
 
 workflow_submitted
 ------------------