Search code examples
markdowngithub-flavored-markdown

What's the best way to create fragment anchors in GitHub markdown?

I'm trying to create fragment anchors to use for link destinations in GitHub markdown. I'm trying to avoid embedding HTML elements since best-practice markdown is to avoid inline HTML.

I'm not talking about heading anchors (though if a heading has non-letter characters, getting auto-generated heading links to work can be a trial-and-error headache). I need to have anchors for arbitrary locations in a .md file.

I've come across GitHub documentation for link reference definitions, but that documentation doesn't really explain clearly how to create an anchor. I tried following Example 168 of creating a link reference without specifying a destination, but that doesn't create an anchor; it just creates a "road to nowhere", so to speak.

What's the best option?

Solution

  • Markdown doesn't support custom anchors out-of-the-box (however, some markdown flavors may do) so you have to use HTML.

    Create an anchor:

    <a name="location"></a>

    Refer to this anchor:

    Take me to something [custom](#location)