Heading in markdown link

If you want a heading inside a link, that does not work. While the # heading is a block element, the [link](href) is an inline element. And it is invalid to have block elements inside inline elements.

So this markdown would produce the wrong result:

[## Heading](/page.html)

❌ This would produce:

<p><a href="/page.html">## Heading</a></p>

What can you do? Swap the elements so that the link is inside the heading:

## [Heading](/page.html)

✅ This would produce:

<h2><a href="/page.html">Heading</a></h2>

Alternatively, you can split it into multiple links if you have multiple elements in that link. Or make it bold instead.

<!-- ✅ Also valid -->
## [Article Title](/article.html)

<!-- ✅ Also valid -->
[**Article Title**

What are blocks and inlines?

From the CommonMark Spec:

We can think of a document as a sequence of blocks—structural elements like paragraphs, block quotations, lists, headings, rules, and code blocks. Some blocks (like block quotes and list items) contain other blocks; others (like headings and paragraphs) contain inline content—text, links, emphasized text, images, code spans, and so on.