diff --git a/bitcoin/examples/ecdsa-psbt.rs b/bitcoin/examples/ecdsa-psbt.rs
index e6bbaf1e6..5aa05ea97 100644
--- a/bitcoin/examples/ecdsa-psbt.rs
+++ b/bitcoin/examples/ecdsa-psbt.rs
@@ -5,7 +5,7 @@
 //!
 //! You can verify the workflow using `bitcoind` and `bitcoin-cli`.
 //!
-//! ## Example Setup
+//! # Example Setup
 //!
 //! 1. Start Bitcoin Core in Regtest mode, for example:
 //!
diff --git a/bitcoin/src/address/mod.rs b/bitcoin/src/address/mod.rs
index ebaf248ac..0a1981245 100644
--- a/bitcoin/src/address/mod.rs
+++ b/bitcoin/src/address/mod.rs
@@ -313,7 +313,7 @@ pub enum AddressData {
 internals::transparent_newtype! {
     /// A Bitcoin address.
     ///
-    /// ### Parsing addresses
+    /// # Parsing addresses
     ///
     /// When parsing string as an address, one has to pay attention to the network, on which the parsed
     /// address is supposed to be valid. For the purpose of this validation, `Address` has
@@ -386,7 +386,7 @@ internals::transparent_newtype! {
     /// assert_eq!(format!("{:?}", address), "132F25rTsvBdp9JzLLBHP5mvGY66i1xdiM");
     /// ```
     ///
-    /// ### Relevant BIPs
+    /// # Relevant BIPs
     ///
     /// * [BIP13 - Address Format for pay-to-script-hash](https://github.com/bitcoin/bips/blob/master/bip-0013.mediawiki)
     /// * [BIP16 - Pay to Script Hash](https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki)
diff --git a/bitcoin/src/bip158.rs b/bitcoin/src/bip158.rs
index 67b55ef9e..512d57001 100644
--- a/bitcoin/src/bip158.rs
+++ b/bitcoin/src/bip158.rs
@@ -11,7 +11,7 @@
 //! is an alternative to Bloom filters, as used in BIP 37, that minimizes filter
 //! size by using Golomb-Rice coding for compression.
 //!
-//! ### Relevant BIPS
+//! # Relevant BIPS
 //!
 //! * [BIP 157 - Client Side Block Filtering](https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki)
 //! * [BIP 158 - Compact Block Filters for Light Clients](https://github.com/bitcoin/bips/blob/master/bip-0158.mediawiki)
diff --git a/bitcoin/src/blockdata/script/mod.rs b/bitcoin/src/blockdata/script/mod.rs
index 1bd2bddf3..dccfe6727 100644
--- a/bitcoin/src/blockdata/script/mod.rs
+++ b/bitcoin/src/blockdata/script/mod.rs
@@ -31,7 +31,7 @@
 //! and forcing them to be larger would waste memory and, in case of Bitcoin script, even some
 //! performance (forcing allocations).
 //!
-//! ## `Script` vs `ScriptBuf` vs `Builder`
+//! # `Script` vs `ScriptBuf` vs `Builder`
 //!
 //! These are the most important types in this module and they are quite similar, so it may seem
 //! confusing what the differences are. `Script` is an unsized type much like `str` or `Path` are
diff --git a/bitcoin/src/consensus/encode.rs b/bitcoin/src/consensus/encode.rs
index c2a751a0f..3620c1867 100644
--- a/bitcoin/src/consensus/encode.rs
+++ b/bitcoin/src/consensus/encode.rs
@@ -284,7 +284,7 @@ pub trait Decodable: Sized {
     /// vector of a limited size, calling this function directly might be marginally faster (due to
     /// avoiding extra checks).
     ///
-    /// ### Rules for trait implementations
+    /// # Rules for trait implementations
     ///
     /// * Simple types that have a fixed size (own and member fields), don't have to overwrite
     ///   this method, or be concern with it.
diff --git a/hashes/src/macros.rs b/hashes/src/macros.rs
index 2c9aa1bcf..162af9a03 100644
--- a/hashes/src/macros.rs
+++ b/hashes/src/macros.rs
@@ -218,7 +218,7 @@ macro_rules! impl_debug_only_for_newtype {
 /// * `Borrow<[u8; $len]>`
 /// * `Borrow<[u8]>`
 ///
-/// ## Parameters
+/// # Parameters
 ///
 /// * `ty` - The bytelike type to implement the traits on.
 /// * `$len` - The number of bytes this type has.
@@ -262,7 +262,7 @@ macro_rules! impl_bytelike_traits {
 ///
 /// (See also [`hex-conservative::fmt_hex_exact`].)
 ///
-/// ## Parameters
+/// # Parameters
 ///
 /// * `ty` - The bytelike type to implement the traits on.
 /// * `$len` - The number of bytes this type has.
diff --git a/primitives/src/block.rs b/primitives/src/block.rs
index 6ac3655d2..e022d3f2b 100644
--- a/primitives/src/block.rs
+++ b/primitives/src/block.rs
@@ -261,7 +261,7 @@ impl From<&Header> for BlockHash {
 ///
 /// > When a block nVersion does not have top bits 001, it is treated as if all bits are 0 for the purposes of deployments.
 ///
-/// ### Relevant BIPs
+/// # Relevant BIPs
 ///
 /// * [BIP9 - Version bits with timeout and delay](https://github.com/bitcoin/bips/blob/master/bip-0009.mediawiki) (current usage)
 /// * [BIP34 - Block v2, Height in Coinbase](https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki)
diff --git a/primitives/src/locktime/absolute.rs b/primitives/src/locktime/absolute.rs
index ad03f5102..d6434ed83 100644
--- a/primitives/src/locktime/absolute.rs
+++ b/primitives/src/locktime/absolute.rs
@@ -24,7 +24,7 @@ pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, P
 /// Used for transaction lock time (`nLockTime` in Bitcoin Core and [`Transaction::lock_time`]
 /// in this library) and also for the argument to opcode `OP_CHECKLOCKTIMEVERIFY`.
 ///
-/// ### Note on ordering
+/// # Note on ordering
 ///
 /// Locktimes may be height- or time-based, and these metrics are incommensurate; there is no total
 /// ordering on locktimes. In order to compare locktimes, instead of using `<` or `>` we provide the
@@ -34,7 +34,7 @@ pub use units::locktime::absolute::{ConversionError, Height, ParseHeightError, P
 /// it easy to store transactions in sorted data structures, and use the locktime's 32-bit integer
 /// consensus encoding to order it.
 ///
-/// ### Relevant BIPs
+/// # Relevant BIPs
 ///
 /// * [BIP-65 OP_CHECKLOCKTIMEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki)
 /// * [BIP-113 Median time-past as endpoint for lock-time calculations](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki)
diff --git a/primitives/src/locktime/relative.rs b/primitives/src/locktime/relative.rs
index 7a08d2296..59dfdd0d6 100644
--- a/primitives/src/locktime/relative.rs
+++ b/primitives/src/locktime/relative.rs
@@ -20,13 +20,13 @@ pub use units::locktime::relative::{Height, Time, TimeOverflowError};
 /// Used for sequence numbers (`nSequence` in Bitcoin Core and [`TxIn::sequence`]
 /// in this library) and also for the argument to opcode `OP_CHECKSEQUENCEVERIFY`.
 ///
-/// ### Note on ordering
+/// # Note on ordering
 ///
 /// Locktimes may be height- or time-based, and these metrics are incommensurate; there is no total
 /// ordering on locktimes. In order to compare locktimes, instead of using `<` or `>` we provide the
 /// [`LockTime::is_satisfied_by`] API.
 ///
-/// ### Relevant BIPs
+/// # Relevant BIPs
 ///
 /// * [BIP 68 Relative lock-time using consensus-enforced sequence numbers](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki)
 /// * [BIP 112 CHECKSEQUENCEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0112.mediawiki)
diff --git a/primitives/src/script/borrowed.rs b/primitives/src/script/borrowed.rs
index 87a97c15b..59e4585fa 100644
--- a/primitives/src/script/borrowed.rs
+++ b/primitives/src/script/borrowed.rs
@@ -19,7 +19,7 @@ internals::transparent_newtype! {
     /// form `&Script`. It is always encoded as a series of bytes representing the opcodes and data
     /// pushes.
     ///
-    /// ## Validity
+    /// # Validity
     ///
     /// `Script` does not have any validity invariants - it's essentially just a marked slice of
     /// bytes. This is similar to [`Path`](std::path::Path) vs [`OsStr`](std::ffi::OsStr) where they
@@ -30,7 +30,7 @@ internals::transparent_newtype! {
     /// allowed to be in a transaction (outputs just become unspendable) and there even are such
     /// transactions in the chain. Thus we must allow such scripts to be placed in the transaction.
     ///
-    /// ## Slicing safety
+    /// # Slicing safety
     ///
     /// Slicing is similar to how `str` works: some ranges may be incorrect and indexing by
     /// `usize` is not supported. However, as opposed to `std`, we have no way of checking
@@ -44,7 +44,7 @@ internals::transparent_newtype! {
     /// It is recommended to use `.instructions()` method to get an iterator over script
     /// instructions and work with that instead.
     ///
-    /// ## Memory safety
+    /// # Memory safety
     ///
     /// The type is `#[repr(transparent)]` for internal purposes only!
     /// No consumer crate may rely on the representation of the struct!
diff --git a/primitives/src/sequence.rs b/primitives/src/sequence.rs
index 75e956941..df291b7ee 100644
--- a/primitives/src/sequence.rs
+++ b/primitives/src/sequence.rs
@@ -81,7 +81,7 @@ impl Sequence {
     /// Instead of this method please consider using `!enables_absolute_lock_time` because it
     /// is equivalent and improves readability for those not steeped in Bitcoin folklore.
     ///
-    /// ## Historical note
+    /// # Historical note
     ///
     /// The term 'final' is an archaic Bitcoin term, it may have come about because the sequence
     /// number in the original Bitcoin code was intended to be incremented in order to replace a
diff --git a/primitives/src/transaction.rs b/primitives/src/transaction.rs
index 640bc8200..28eadde17 100644
--- a/primitives/src/transaction.rs
+++ b/primitives/src/transaction.rs
@@ -52,7 +52,7 @@ use crate::witness::Witness;
 ///
 /// * [CTtransaction definition](https://github.com/bitcoin/bitcoin/blob/345457b542b6a980ccfbc868af0970a6f91d1b82/src/primitives/transaction.h#L279)
 ///
-/// ### Serialization notes
+/// # Serialization notes
 ///
 /// If any inputs have nonempty witnesses, the entire transaction is serialized
 /// in the post-BIP141 SegWit format which includes a list of witnesses. If all
@@ -83,7 +83,7 @@ use crate::witness::Witness;
 /// We therefore deviate from the spec by always using the SegWit witness encoding
 /// for 0-input transactions, which results in unambiguously parseable transactions.
 ///
-/// ### A note on ordering
+/// # A note on ordering
 ///
 /// This type implements `Ord`, even though it contains a locktime, which is not
 /// itself `Ord`. This was done to simplify applications that may need to hold
@@ -103,7 +103,7 @@ pub struct Transaction {
     pub version: Version,
     /// Block height or timestamp. Transaction cannot be included in a block until this height/time.
     ///
-    /// ### Relevant BIPs
+    /// # Relevant BIPs
     ///
     /// * [BIP-65 OP_CHECKLOCKTIMEVERIFY](https://github.com/bitcoin/bips/blob/master/bip-0065.mediawiki)
     /// * [BIP-113 Median time-past as endpoint for lock-time calculations](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki)
diff --git a/units/src/result.rs b/units/src/result.rs
index bf57d30fc..3d1ee003d 100644
--- a/units/src/result.rs
+++ b/units/src/result.rs
@@ -22,7 +22,7 @@ use crate::{Amount, FeeRate, SignedAmount, Weight};
 ///
 /// The `NumOpResult` type provides protection against overflow and div-by-zero.
 ///
-/// ## Overflow protection
+/// ### Overflow protection
 ///
 /// ```
 /// # use bitcoin_units::{amount, Amount};
@@ -48,7 +48,7 @@ use crate::{Amount, FeeRate, SignedAmount, Weight};
 /// # Ok::<_, amount::OutOfRangeError>(())
 /// ```
 ///
-/// ## Divide-by-zero (overflow in `Div` or `Rem`)
+/// ### Divide-by-zero (overflow in `Div` or `Rem`)
 ///
 /// In some instances one may wish to differentiate div-by-zero from overflow.
 ///