Explain Codes LogoExplain Codes Logo

In Markdown, what is the best way to link to a fragment of a page, i.e. #some_id?

html
markdown
anchors
linking
Alex KataevbyAlex KataevΒ·Dec 26, 2024
⚑TLDR

Linking to a page fragment in Markdown follows the syntax [Text](#id). Be certain the target element has a matching id attribute.

[Jump to Summary](#summary)

The target should carry a similar id:

<h2 id="summary">Summary Header</h2> <!-- Note: This id should never be an emoji. 🚫🐡 -->

An alternate way of creating a destination while preserving layout aesthetics can be achieved with <a> tags:

<a name="summary"></a>

Summary Header

<!-- Jackpot Destination! Adventure awaits. πŸš€ -->
## Creating Markdown Anchors (Quick & Clean)
### HTML-Markdown Fusion: Applied Sorcery 

Occasionally, you might need to insert an **anchor** within your Markdown for internal navigation. Here’s the secret spell:

```html
<!-- Casting the anchor spell -->
<a name="anchor-name"></a>
<!-- Now you see me...πŸŽ©πŸ‡ -->

You might fancy an id directly placed within paragraph tags:

<p id="paragraph-anchor">Land right here, fellow coder.</p> <!-- It's like parking space for your cursor. πŸ›Έ -->

Impact-free Anchoring: Don't Break the Layout

When playing around with anchors, maintain an impact-free layout. Conjure up anchor points that won’t disturb the natural flow of your document:

<a name="minimal-layout-impact"></a> <!-- Cute and harmless as a hamster. 🐹 -->

To jump straight to it:

[Link to Section](#minimal-layout-impact) <!-- One click teleportation service. 🌌 -->

Keeping it Compatible: TFS 2015 and Special Characters

When your playground includes platforms like TFS 2015, keep emojis and other special characters away from ids to avoid breaking preview extensions or functionalities.

Paragraph Linking: Point and Click!

By placing an id inside paragraph tags, you can create anchor links pointing to specific sections of your text. For improved user understanding, provide a brief description when sharing a link:

[See the detailed explanation](#detailed-explanation) <!-- Isn't it like reading a map? πŸ—ΊοΈ --> ... <p id="detailed-explanation">This is important. Look closely.</p> <!-- Catch the wisdom nuggets! πŸ¦‰ -->

Practical Tips and Advanced Techniques

Jekyll: Autogenerated Ids for Headings

Markdown users will rejoice knowing that in Jekyll, every heading is conveniently bestowed with an id, making section linking a breeze. Moreover, no extra markup is needed:

# Hello, I'm a linkable header! <!-- I'm armed with my very own id! πŸŽ–οΈ -->

PHP Markdown Extra: Custom Ids for Headers

Ever felt the regular Markdown syntax is too restraining? PHP Markdown Extra brings you an easy way to add custom ids to your headers:

## I'm special! Look at my id {#custom-id} <!-- Who wouldn't want a custom id? 😎 -->

To sneak back to this special section:

[Back to Special](#custom-id) <!-- Backtracking in style! πŸ•Ί -->

W3C Standards: When in Doubt, Check it Out

Choosing to follow W3C best practices with id attributes ensures cross-browser compatibility and your code remains in line with international standards.