Markdown Anchor Link
How to link to headings and sections within a markdown document. GitHub auto-generates heading anchors. Syntax and examples.
What is markdown anchor link?
Anchor links (also called internal links or jump links) allow you to link to a specific section within the same document. Markdown parsers automatically generate ID attributes for headings based on the heading text, which you can reference with a # in a regular markdown link.
Syntax
Link to a heading
The anchor is derived from the heading text: lowercase, spaces replaced with hyphens, punctuation removed.
In table of contents
Anchor links are the backbone of manually-written tables of contents.
- Introduction ...
Heading → anchor conversion
Rules: lowercase everything, replace spaces with -, remove special characters except hyphens.
Platform support
| Platform | Supported | Notes |
|---|---|---|
| GitHub | Yes | Auto-generates heading IDs |
| GitLab | Yes | — |
| Obsidian | Yes | Use [[Page#Heading]] for cross-file links |
| Notion | No | Links to blocks available via share menu, not markdown |
| Discord | No | — |
| Slack | No | — |
Common mistakes
[Link](#My Section)
[Link](#my-section)
Heading IDs are lowercase with hyphens. "My Section" becomes #my-section, not #My-Section.
[Link](#api-reference-(v2))
[Link](#api-reference-v2)
Parentheses and most special characters are removed when generating heading IDs.
Tips for anchor link
Tools like MarkdownTools TOC Generator automatically create correct anchor links for all your headings, handling the ID conversion rules.
Different markdown parsers handle special characters in heading IDs slightly differently. Always test anchor links in your target platform.
Frequently asked questions
Everything you need to know.
How do I link to a specific section in a markdown document?
Use a standard link with a # followed by the heading ID: [Section Name](#section-name). The ID is the heading text lowercased with spaces replaced by hyphens.
Related elements
Link
Links in markdown use square brackets for the display text and parentheses for the URL: [text](url). You can also add hover titles, use reference-style links for cleaner source, and auto-link bare URLs on most platforms.
Heading
Markdown headings are created with hash symbols (#). One hash for H1 (largest), two for H2, up to six for H6 (smallest). Headings structure your document and create a hierarchy that readers and search engines can follow.
Table
Markdown tables use pipes (|) and hyphens (-) to create rows and columns. The second row defines column alignment with colons. Tables are ideal for structured data, comparisons, and reference material.
Try it in the editor
Paste your markdown and see anchor link rendered instantly with professional themes.