How to link to headings and sections within a markdown document. GitHub auto-generates heading anchors. Syntax and examples.
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.
The anchor is derived from the heading text: lowercase, spaces replaced with hyphens, punctuation removed.
Anchor links are the backbone of manually-written tables of contents.
Rules: lowercase everything, replace spaces with -, remove special characters except hyphens.
| 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 | — |
[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.
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.
Everything you need to know.
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.
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.
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.
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.
Paste your markdown and see anchor link rendered instantly with professional themes.