Consider the following structure with documentation:

/// Item docs.
///
#[doc="Hello there!"]
///
/// # Example
///
/// ```rust
/// // some code here
/// ```
pub struct NonGen;

At present, rustdoc will render this as:

Item docs.

Hello there!

# Example

// some code here

When the following is expected:

Item docs.

Hello there!

Example

// some code here

In short, after a #[doc] attribute, a markdown header is not interpreted as markdown.

This also applies to headers declared using ===, where

Example
=======

is rendered by rustdoc as:

Example =======

as opposed to the expected:

Example

I wouldn't be surprised if this is a more systemic issue and additional markdown syntax is interpreted literally as well.