diff --git a/docs/dev-info.rst b/docs/dev-info.rst
--- a/docs/dev-info.rst
+++ b/docs/dev-info.rst
@@ -22,14 +22,14 @@
 To simplify the use, the following makefile targets can be used:
 
 schema
-~~~~~~
+^^^^^^
 
 .. code:: shell
 
     make db-create db-prepare db-migrate
 
 data
-~~~~
+^^^^
 
 Once the db is created, you need some data to be injected (request
 types, client, collection, etc...):
@@ -65,7 +65,7 @@
         url: https://hal.inria.fr
 
 drop
-~~~~
+^^^^
 
 For information, you can drop the db:
 
@@ -80,7 +80,7 @@
 properly.
 
 Configuration
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 **``{/etc/softwareheritage | ~/.config/swh | ~/.swh}``/deposit/server.yml**:
 
@@ -101,7 +101,7 @@
     max_upload_size: 20971520
 
 Run
-~~~
+^^^
 
 Run the local server, using the default configuration file:
 
@@ -118,7 +118,7 @@
 This is more close to what's actually running in production.
 
 Configuration
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 This expects the same file describes in the previous chapter. Plus, an
 additional private section file containing private information that is
@@ -147,7 +147,7 @@
         password: user-password
 
 Run
-~~~
+^^^
 
 .. code:: shell
 
diff --git a/docs/metadata.rst b/docs/metadata.rst
--- a/docs/metadata.rst
+++ b/docs/metadata.rst
@@ -54,7 +54,7 @@
 --------
 
 Using only Atom
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 
 .. code:: xml
 
@@ -73,7 +73,7 @@
     </entry>
 
 Using Atom with CodeMeta
-~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code:: xml
 
@@ -138,7 +138,7 @@
         </entry>
 
 Using Atom with DublinCore and CodeMeta (multi-schema entry)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. code:: xml
 
diff --git a/docs/specs/blueprint.rst b/docs/specs/blueprint.rst
--- a/docs/specs/blueprint.rst
+++ b/docs/specs/blueprint.rst
@@ -1,5 +1,5 @@
 Use cases
----------
+=========
 
 The general idea is that a deposit can be created either in a single request
 or by multiple requests to allow the user to add elements to the deposit piece
@@ -52,7 +52,7 @@
 
 
 Deposit creation
-~~~~~~~~~~~~~~~~
+----------------
 
 From client's deposit repository server to SWH's repository server:
 
@@ -109,7 +109,7 @@
 
 
 Updating an existing deposit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""""""
 
 5. Client updates existing deposit through the *update uris* (one or more POST
    or PUT requests to either the *edit-media iri* or *edit iri*).
@@ -138,7 +138,7 @@
 
 
 Schema representation
-^^^^^^^^^^^^^^^^^^^^^
+"""""""""""""""""""""
 
 Scenario: updating a deposit via SWORDv2_ protocol:
 
@@ -147,7 +147,7 @@
 
 
 Deleting deposit (or associated archive, or associated metadata)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 
 6. Deposit deletion is possible as long as the deposit is still in ``partial``
    state.
@@ -166,13 +166,13 @@
 
 
 Client asks for operation status
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""""""""""
 
 7. Operation status can be read through a GET query to the *state iri*.
 
 
 Server: Triggering deposit checks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""""""""""""""
 
 Once the status ``deposited`` is reached for a deposit, checks for the
 associated archive(s) and metadata will be triggered. If those checks
@@ -181,7 +181,7 @@
 
 
 Server: Triggering deposit load
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""""""""""""
 
 Once the status ``verified`` is reached for a deposit, loading the
 deposit with its associated metadata will be triggered.
diff --git a/docs/specs/protocol-reference.rst b/docs/specs/protocol-reference.rst
--- a/docs/specs/protocol-reference.rst
+++ b/docs/specs/protocol-reference.rst
@@ -1,7 +1,7 @@
 .. _deposit-protocol:
 
 Protocol reference
-~~~~~~~~~~~~~~~~~~
+==================
 
 The swh-deposit protocol is an extension SWORDv2_ protocol, and the
 swh-deposit client and server should work with any other SWORDv2-compliant
@@ -17,10 +17,10 @@
 
 
 Origin creation with the ``<swhdeposit:create_origin>`` tag
-===========================================================
+-----------------------------------------------------------
 
 Motivation
-----------
+^^^^^^^^^^
 
 This is the main extension we define.
 This tag is used after a deposit is completed, to load it in the Software Heritage
@@ -33,7 +33,7 @@
 have an URL.
 
 Usage
------
+^^^^^
 
 Instead, clients are expected to provide the origin URL themselves, by adding
 a tag in the Atom entry they submit to the server, like this:
@@ -59,7 +59,7 @@
 the source code artifacts of this deposit.
 
 Semantics of origin URLs
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Origin URLs must be unique to an origin, ie. to a software project.
 The exact definition of a "software project" is left to the clients of the deposit.
@@ -80,7 +80,7 @@
 ``https://example.org/foo/``.
 
 Fallbacks
----------
+^^^^^^^^^
 
 If the ``<swhdeposit:create_origin>`` is not provided (either because they are generic
 SWORDv2 implementations or old implementations of an swh-deposit client), the server
@@ -93,7 +93,7 @@
 
 
 Adding releases to an origin, with the ``<swhdeposit:add_to_origin>`` tag
-=========================================================================
+-------------------------------------------------------------------------
 
 When depositing a source code artifact for an origin (ie. software project) that
 was already deposited before, clients should not use ``<swhdeposit:create_origin>``,
@@ -128,10 +128,10 @@
 
 
 Metadata
-========
+--------
 
 Format
-------
+^^^^^^
 
 While the SWORDv2 specification recommends the use of DublinCore_,
 we prefer the CodeMeta_ vocabulary, as we already use it in other components
@@ -200,7 +200,7 @@
 .. _mandatory-attributes:
 
 Mandatory attributes
---------------------
+^^^^^^^^^^^^^^^^^^^^
 
 All deposits must include:
 
@@ -213,7 +213,7 @@
 .. _metatadata-only-deposit
 
 Metadata-only deposit
-=====================
+---------------------
 
 The swh-deposit server can also be without a source code artifact, but only
 to provide metadata that describes an arbitrary origin or object in
diff --git a/docs/specs/spec-meta-deposit.rst b/docs/specs/spec-meta-deposit.rst
--- a/docs/specs/spec-meta-deposit.rst
+++ b/docs/specs/spec-meta-deposit.rst
@@ -1,10 +1,10 @@
 .. _spec-metadata-deposit:
 
 The metadata-only deposit
-^^^^^^^^^^^^^^^^^^^^^^^^^
+=========================
 
 Goal
-====
+----
 
 A client may wish to deposit only metadata about an origin or object already
 present in the Software Heritage archive.
@@ -14,7 +14,7 @@
 the metadata about an object in the archive.
 
 Requirements
-============
+------------
 
 1. Create a metadata-only deposit through a :ref:`POST request<API-create-deposit>`
 2. It is composed of ONLY one Atom XML document
@@ -35,7 +35,7 @@
 .. _qualifiers: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#qualifiers
 
 A complete metadata example
-===========================
+---------------------------
 The reference element is included in the metadata xml atomEntry under the
 swh namespace:
 
@@ -72,14 +72,14 @@
   </entry>
 
 References
-==========
+----------
 
 The metadata reference can be either on:
 - an origin
 - a graph object (core SWHID with or without qualifiers)
 
 Origins
--------
+^^^^^^^
 
 The metadata may be on an origin, identified by the origin's URL:
 
@@ -92,7 +92,7 @@
   </swh:deposit>
 
 Graph objects
--------------
+^^^^^^^^^^^^^
 
 It may also reference an object in the `SWH graph <data-model>`: contents,
 directories, revisions, releases, and snapshots:
@@ -129,7 +129,7 @@
 
 
 Loading procedure
-=================
+-----------------
 
 In this case, the metadata-deposit will be injected as a metadata entry of
 the relevant object, with the information about the contributor of the deposit.
diff --git a/docs/user-manual.rst b/docs/user-manual.rst
--- a/docs/user-manual.rst
+++ b/docs/user-manual.rst
@@ -340,7 +340,7 @@
 piece by piece. The steps to create a multisteps deposit:
 
 1. Create an partial deposit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""""""""""""""""""""""""""""
 
 First use the ``--partial`` argument to declare there is more to come
 
@@ -352,7 +352,7 @@
 
 
 2. Add content or metadata to the deposit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""""""""""""""""""""""
 
 Continue the deposit by using the ``--deposit-id`` argument given as a response
 for the first step. You can continue adding content or metadata while you use
@@ -378,7 +378,7 @@
 
 
 3. Finalize deposit
-~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""
 
 On your last addition (same command as before), by not declaring it
 ``--partial``, the deposit will be considered completed. Its status will be