diff --git a/docs/contracts/constant-state-variables.rst b/docs/contracts/constant-state-variables.rst
index 33204f58d..06bc4189e 100644
--- a/docs/contracts/constant-state-variables.rst
+++ b/docs/contracts/constant-state-variables.rst
@@ -21,7 +21,7 @@ is copied to all the places in the code where they are accessed. For these value
 can sometimes be cheaper than immutable values.
 
 Not all types for constants and immutables are implemented at this time. The only supported types are
-`strings <strings>`_ (only for constants) and `value types <value-types>`_.
+:ref:`strings <strings>` (only for constants) and :ref:`value types <value-types>`.
 
 ::
 
diff --git a/docs/contracts/inheritance.rst b/docs/contracts/inheritance.rst
index f628d49fb..533f74da4 100644
--- a/docs/contracts/inheritance.rst
+++ b/docs/contracts/inheritance.rst
@@ -331,7 +331,7 @@ Modifier Overriding
 ===================
 
 Function modifiers can override each other. This works in the same way as
-`function overriding <function-overriding>`_ (except that there is no overloading for modifiers). The
+:ref:`function overriding <function-overriding>` (except that there is no overloading for modifiers). The
 ``virtual`` keyword must be used on the overridden modifier
 and the ``override`` keyword must be used in the overriding modifier:
 
diff --git a/docs/examples/micropayment.rst b/docs/examples/micropayment.rst
index b68de3cad..2ff293f48 100644
--- a/docs/examples/micropayment.rst
+++ b/docs/examples/micropayment.rst
@@ -114,7 +114,7 @@ In general, ECDSA signatures consist of two parameters,
 parameter called ``v``, that you can use to verify which
 account's private key was used to sign the message, and
 the transaction's sender. Solidity provides a built-in
-function `ecrecover <mathematical-and-cryptographic-functions>`_ that
+function :ref:`ecrecover <mathematical-and-cryptographic-functions>` that
 accepts a message along with the ``r``, ``s`` and ``v`` parameters
 and returns the address that was used to sign the message.
 
@@ -127,7 +127,7 @@ apart. You can do this on the client-side, but doing it inside
 the smart contract means you only need to send one signature
 parameter rather than three. Splitting apart a byte array into
 its constituent parts is a mess, so we use
-`inline assembly <assembly>`_ to do the job in the ``splitSignature``
+:doc:`inline assembly <assembly>` to do the job in the ``splitSignature``
 function (the third function in the full contract at the end of this section).
 
 Computing the Message Hash
diff --git a/docs/layout-of-source-files.rst b/docs/layout-of-source-files.rst
index d80af49f7..6c0dd0a16 100644
--- a/docs/layout-of-source-files.rst
+++ b/docs/layout-of-source-files.rst
@@ -22,7 +22,7 @@ Every source file should start with a comment indicating its license:
 
 The compiler does not validate that the license is part of the
 `list allowed by SPDX <https://spdx.org/licenses/>`_, but
-it does include the supplied string in the `bytecode metadata <metadata>`_.
+it does include the supplied string in the :ref:`bytecode metadata <metadata>`.
 
 If you do not want to specify a license or if the source code is
 not open-source, please use the special value ``UNLICENSED``.
diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index 30ceec3a9..3b52d7c47 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -1149,7 +1149,7 @@ Add comments above functions or contracts following `doxygen <http://www.doxygen
 of one or multiple lines starting with ``///`` or a
 multiline comment starting with ``/**`` and ending with ``*/``.
 
-For example, the contract from `a simple smart contract <simple-smart-contract>`_ with the comments
+For example, the contract from :ref:`a simple smart contract <simple-smart-contract>` with the comments
 added looks like the one below::
 
     // SPDX-License-Identifier: GPL-3.0
@@ -1176,6 +1176,6 @@ added looks like the one below::
         }
     }
 
-It is recommended that Solidity contracts are fully annotated using `NatSpec <natspec>`_ for all public interfaces (everything in the ABI).
+It is recommended that Solidity contracts are fully annotated using :ref:`NatSpec <natspec>` for all public interfaces (everything in the ABI).
 
-Please see the section about `NatSpec <natspec>`_ for a detailed explanation.
+Please see the section about :ref:`NatSpec <natspec>` for a detailed explanation.
diff --git a/docs/units-and-global-variables.rst b/docs/units-and-global-variables.rst
index a32900a50..a84cc555e 100644
--- a/docs/units-and-global-variables.rst
+++ b/docs/units-and-global-variables.rst
@@ -160,6 +160,8 @@ more details on error handling and when to use which function.
 
 .. index:: keccak256, ripemd160, sha256, ecrecover, addmod, mulmod, cryptography,
 
+.. _mathematical-and-cryptographic-functions:
+
 Mathematical and Cryptographic Functions
 ----------------------------------------