diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst
index 7a742d5..da958b7 100644
--- a/docs/design/auth-framework.rst
+++ b/docs/design/auth-framework.rst
@@ -953,9 +953,11 @@
 `rsa+ecdsa` enables support for both rsa and ecdsa algorithms in the mbedTLS
 library.
 
-Note: If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
-be defined in the platform Makefile. It will make mbed TLS use an implementation
-of SHA-256 with smaller memory footprint (~1.5 KB less) but slower (~30%).
+.. note::
+   If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
+   be defined in the platform Makefile. It will make mbed TLS use an
+   implementation of SHA-256 with smaller memory footprint (~1.5 KB less) but
+   slower (~30%).
 
 --------------
 
diff --git a/docs/design/firmware-design.rst b/docs/design/firmware-design.rst
index 710d26d..21b8234 100644
--- a/docs/design/firmware-design.rst
+++ b/docs/design/firmware-design.rst
@@ -1141,8 +1141,10 @@
    ``bl31_register_bl32_init()`` which provides a SPD-defined mechanism to
    invoke a 'world-switch synchronous call' to Secure-EL1 to run the BL32
    entrypoint.
-   NOTE: The Test SPD service included with TF-A provides one implementation
-   of such a mechanism.
+
+   .. note::
+      The Test SPD service included with TF-A provides one implementation
+      of such a mechanism.
 
    On completion BL32 returns control to BL31 via a SMC, and on receipt the
    SPD service handler invokes the synchronous call return mechanism to return
@@ -1675,8 +1677,9 @@
 illustrated for both FVP and Juno in the following diagrams, using the TSP as
 an example.
 
-Note: Loading the BL32 image in TZC secured DRAM doesn't change the memory
-layout of the other images in Trusted SRAM.
+.. note::
+   Loading the BL32 image in TZC secured DRAM doesn't change the memory
+   layout of the other images in Trusted SRAM.
 
 CONFIG section in memory layouts shown below contains:
 
@@ -2215,8 +2218,9 @@
        |       Code        |
        +-------------------+ BLx_BASE
 
-Note: The 2KB alignment for the exception vectors is an architectural
-requirement.
+.. note::
+   The 2KB alignment for the exception vectors is an architectural
+   requirement.
 
 The read-write data start on a new memory page so that they can be mapped with
 read-write permissions, whereas the code and read-only data below are configured
diff --git a/docs/design/interrupt-framework-design.rst b/docs/design/interrupt-framework-design.rst
index b19f7f7..f68cf21 100644
--- a/docs/design/interrupt-framework-design.rst
+++ b/docs/design/interrupt-framework-design.rst
@@ -416,8 +416,9 @@
 Test secure payload dispatcher behavior
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Note:** where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
-``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
+.. note::
+   Where this document discusses ``TSP_NS_INTR_ASYNC_PREEMPT`` as being
+   ``1``, the same results also apply when ``EL3_EXCEPTION_HANDLING`` is ``1``.
 
 The TSPD only handles Secure-EL1 interrupts and is provided with the following
 routing model at build time.
diff --git a/docs/design/reset-design.rst b/docs/design/reset-design.rst
index b5c9bb4..ccd717a 100644
--- a/docs/design/reset-design.rst
+++ b/docs/design/reset-design.rst
@@ -23,10 +23,11 @@
 guide the platform integrator by indicating which build options exclude which
 steps, depending on the capability of the platform.
 
-Note: If BL31 is used as the TF-A entry point instead of BL1, the diagram
-above is still relevant, as all these operations will occur in BL31 in
-this case. Please refer to section 6 "Using BL31 entrypoint as the reset
-address" for more information.
+.. note::
+   If BL31 is used as the TF-A entry point instead of BL1, the diagram
+   above is still relevant, as all these operations will occur in BL31 in
+   this case. Please refer to section 6 "Using BL31 entrypoint as the reset
+   address" for more information.
 
 Programmable CPU reset address
 ------------------------------
diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst
index dbe2f2a..6f648f5 100644
--- a/docs/design/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
@@ -141,8 +141,9 @@
    compared with the hash of the ROTPK read from the trusted root-key storage
    registers. If they match, the BL2 hash is read from the certificate.
 
-   Note: the matching operation is platform specific and is currently
-   unimplemented on the Arm development platforms.
+   .. note::
+      The matching operation is platform specific and is currently
+      unimplemented on the Arm development platforms.
 
 -  BL1 loads the BL2 image. Its hash is calculated and compared with the hash
    read from the certificate. Control is transferred to the BL2 image if all