# HG changeset patch
# User Goffi <goffi@goffi.org>
# Date 1668171082 -3600
# Node ID 97fbe11c4476da0f78c5b249b72f3c9f4f6bad86
# Parent  6fa4ca0c047e59012d76fc415e7f2cd345dea694
doc (components/AP Gateway): `html_redirect_dict` option

diff -r 6fa4ca0c047e -r 97fbe11c4476 doc/components.rst
--- a/doc/components.rst	Fri Nov 11 13:51:20 2022 +0100
+++ b/doc/components.rst	Fri Nov 11 13:51:22 2022 +0100
@@ -244,6 +244,87 @@
 
   **default**: ``true``
 
+``html_redirect_dict``
+  A dictionary use to redirect HTTP requests when it's not an ActivityPub request (i.e.
+  when the ``Accept`` header is not set to ``application/json``). Several ActivityPub
+  implementations link to original server when clicking on some links such as post author
+  or item ID, and this result in a request to the corresponding ActivityPub endpoint, but
+  made to retrieve HTML instead of ActivityPub JSON data.
+
+  By default, this request is showing the corresponding AP JSON data, but if you set HTML
+  redirection, you can redirect the page to your XMPP client web frontend (or anything
+  making sense), which results in better user experience.
+
+  The expected dictionary is a mapping URL request types to destination URL.
+
+  The URL request types is the first path element after ``ap_path``, it can be:
+
+  ``actor``
+    Actor information. It should link to the profile page of the corresponding XMPP entity
+
+  ``item``
+    A specific publication. It should link to the rendered item
+
+  ``followers``
+    Entities publicly subscribed to the actor. It is usually not used for redirection.
+
+  ``following``
+    Entities that the actor is publicly subscribed to. It is usually not used for
+    redirection.
+
+  In the target URL you can uses template values in curly braces (something like
+  ``{item}``). The values that you can use are:
+
+  ``jid``
+    Full JID corresponding to the AP actor.
+
+  ``jid_user``
+    Only the user part of the JID (what is before the ``@``)
+
+  ``node``
+    Name of the pubsub node corresponding to the AP actor.
+
+  ``item``
+    ID of the XMPP pubsub item.
+
+  You can use a slash ``/`` followed by a part of a node name to filter only on specific
+  nodes. For instance, if you want to redirect microblog items to a different URL that
+  event items, you can use ``item/urn:xmpp:microblog:0`` and ``item/urn:xmpp:events:0``,
+  the first redirection to match will be used. Note that anything containing the filter
+  value will match, thus you can also use ``item/microblog`` (but it then would match an
+  event which has ``microblog`` in is node name).
+
+  You can also use a dictionary as value instead of the target URL. This can be useful to
+  filter on an other value than the node name, if you want to make specific redirection
+  for a particular user for instance. If you use a dictionary, you must use a ``url`` key
+  with the target URL (which may have template values as usual), and you may use a
+  ``filters`` key mapping to an other dictionary where each key is a filter on a specific
+  template value (in other words: key is the template value, like ``jid`` or ``node``, and
+  value is the filter to match).
+
+  *examples*
+
+  Redirect actor page to ``/profile/<JID user part>``, blogs items to ``/blog/<full
+  JID>/<node name>/<item id>`` and events items to ``/event/<full JID>/<node name>/<item
+  id>`` ::
+
+    html_redirect_dict = {
+      "actor": "/profile/{jid_user}",
+      "item/microblog": "/blog/{jid}/{node}/{item}",
+      "item/events": "/event/{jid}/{node}/{item}"
+    }
+
+  Redirect items of user ``louise@example.org`` to ``/b/<item>``::
+
+    html_redirect_dict = {
+      "item": {
+        "url": "/b/{item}",
+        filters: {
+          "jid": "louise@example.org"
+        }
+      }
+    }
+
 
 .. _ap-actor-from-xmpp: