diff --git a/docs/persistent-identifiers.rst b/docs/persistent-identifiers.rst
--- a/docs/persistent-identifiers.rst
+++ b/docs/persistent-identifiers.rst
@@ -279,8 +279,8 @@
 Identifiers with qualifiers
 ---------------------------
 
-* The following `SWHID
-  <https://archive.softwareheritage.org/swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9;anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;path=/Examples/SimpleFarm/simplefarm.ml;lines=9-15>`__
+* The following :swh_web:`SWHID
+  <swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9;anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;path=/Examples/SimpleFarm/simplefarm.ml;lines=9-15>`
   denotes the lines 9 to 15 of a file content that can be found at absolute
   path ``/Examples/SimpleFarm/simplefarm.ml`` from the root directory of the
   revision ``swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0`` that is
@@ -295,8 +295,8 @@
       path=/Examples/SimpleFarm/simplefarm.ml;
       lines=9-15
 
-* Here is an example of a `SWHID
-  <https://archive.softwareheritage.org/swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04;origin=https://github.com/web-platform-tests/wpt;visit=swh:1:snp:b37d435721bbd450624165f334724e3585346499;anchor=swh:1:rev:259d0612af038d14f2cd889a14a3adb6c9e96d96;path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%3Burl=foo/>`__
+* Here is an example of a :swh_web:`SWHID
+  <swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04;origin=https://github.com/web-platform-tests/wpt;visit=swh:1:snp:b37d435721bbd450624165f334724e3585346499;anchor=swh:1:rev:259d0612af038d14f2cd889a14a3adb6c9e96d96;path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%3Burl=foo/>`
   with a file path that requires percent-escaping::
 
     swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04;
@@ -325,7 +325,7 @@
 
 SWHIDs are also automatically computed by Software Heritage for all archived
 objects as part of its archival activity, and can be looked up via the project
-`Web interface <https://archive.softwareheritage.org>`_.
+:swh_web:`Web interface <>`.
 
 This has various practical implications:
 
@@ -345,25 +345,25 @@
 Software Heritage resolver
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-SWHIDs can be resolved using the Software Heritage `Web interface
-<https://archive.softwareheritage.org>`_. In particular, the **root endpoint**
+SWHIDs can be resolved using the Software Heritage :swh_web:`Web interface <>`.
+In particular, the **root endpoint**
 ``/`` can be given a SWHID and will lead to the browsing page of the
 corresponding object, like this:
 ``https://archive.softwareheritage.org/<identifier>``.
 
-A **dedicated** ``/resolve`` **endpoint** of the Software Heritage `Web API
-<https://archive.softwareheritage.org/api/>`_ is also available to
+A **dedicated** ``/resolve`` **endpoint** of the Software Heritage :swh_web:`Web API
+<api/>` is also available to
 programmatically resolve SWHIDs; see: :http:get:`/api/1/resolve/(swhid)/`.
 
 Examples:
 
-* `<https://archive.softwareheritage.org/swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`_
-* `<https://archive.softwareheritage.org/swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`_
-* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`_
-* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`_
-* `<https://archive.softwareheritage.org/api/1/resolve/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`_
-* `<https://archive.softwareheritage.org/swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9;anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;path=/Examples/SimpleFarm/simplefarm.ml;lines=9-15>`_
-* `<https://archive.softwareheritage.org/swh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04;origin=https://github.com/web-platform-tests/wpt;visit=swh:1:snp:b37d435721bbd450624165f334724e3585346499;anchor=swh:1:rev:259d0612af038d14f2cd889a14a3adb6c9e96d96;path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%3Burl=foo/>`_
+* :swh_web:`<swh:1:cnt:94a9ed024d3859793618152ea559a168bbcbb5e2>`
+* :swh_web:`<swh:1:dir:d198bc9d7a6bcf6db04f476d29314f157507d505>`
+* :swh_web:`<api/1/resolve/swh:1:rev:309cf2674ee7a0749978cf8265ab91a60aea0f7d>`
+* :swh_web:`<api/1/resolve/swh:1:rel:22ece559cc7cc2364edc5e5593d63ae8bd229f9f>`
+* :swh_web:`<api/1/resolve/swh:1:snp:c7c108084bc0bf3d81436bf980b46e98bd338453>`
+* :swh_web:`<swh:1:cnt:4d99d2d18326621ccdd70f5ea66c2e2ac236ad8b;origin=https://gitorious.org/ocamlp3l/ocamlp3l_cvs.git;visit=swh:1:snp:d7f1b9eb7ccb596c2622c4780febaa02549830f9;anchor=swh:1:rev:2db189928c94d62a3b4757b3eec68f0a4d4113f0;path=/Examples/SimpleFarm/simplefarm.ml;lines=9-15>`
+* :swh_web:`<wh:1:cnt:f10371aa7b8ccabca8479196d6cd640676fd4a04;origin=https://github.com/web-platform-tests/wpt;visit=swh:1:snp:b37d435721bbd450624165f334724e3585346499;anchor=swh:1:rev:259d0612af038d14f2cd889a14a3adb6c9e96d96;path=/html/semantics/document-metadata/the-meta-element/pragma-directives/attr-meta-http-equiv-refresh/support/x%3Burl=foo/>`
 
 
 Third-party resolvers