Docs

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:

input.md

[## Heading](/page.html)

output.html ❌

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

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

input.md

## [Heading](/page.html)

output.html ✅

<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)
[_Subtitle_](/article.html)
<!-- ✅ Also valid -->
[**Article Title**
_Subtitle_](/article.html)

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.