Markdown Link Syntax Guide: Links, Images & References
Markdown link syntax guide for inline, reference, anchor, relative, email, and HTML links—learn to write cleaner docs and avoid broken links.
Introduction
Markdown link syntax is the set of rules used to create clickable links in Markdown. If you work in a README.md, publish docs, write blog posts, or keep notes in apps like Obsidian or Notion, links are the connective tissue that makes content navigable and practical. A solid Markdown basics foundation helps, but links deserve their own guide because they appear in almost every document and are easy to break.
This guide covers the link types you’ll use most: inline links, reference-style links, anchor links, relative links, email links, and HTML links. You’ll also see how Markdown behaves in CommonMark, GitHub Flavored Markdown (GFM), GitHub, GitLab, VS Code, Obsidian, Notion, static site generators, and documentation sites.
Markdown behavior is not identical everywhere. CommonMark, the CommonMark specification, and app-specific Markdown parser implementations can handle edge cases differently, so practical testing matters more than memorizing trivia. That is especially true when you move between docs, blogs, and note-taking tools.
Good links are about more than rendering correctly. They should be easy to maintain, readable in source form, and accessible to people using screen readers or other assistive tools. If you already know plain text formatting, this guide will help you use links with more confidence.
What is Markdown link syntax?
Markdown link syntax is the pattern that turns plain text into a hyperlink. The basic form is [link text](https://example.com), where the brackets contain the visible text and the parentheses contain the destination URL. In Markdown, this is the most common way to create a link.
For example:
[Markdown cheat sheet](https://markdownmastery.com/blog/markdown-cheat-sheet)[Markdown formatting guide](https://markdownmastery.com/blog/content-formatting-guide-for-markdown)
A Markdown parser converts that syntax into an HTML anchor tag with an href attribute. If you add a title, the parser may also output a title attribute.
How do you create a link in Markdown?
To create a link in Markdown, write the link text in brackets and the URL in parentheses:
[Visit the guide](https://example.com)
You can also use an optional title:
[Visit the guide](https://example.com "Open the guide")
That title may appear as a tooltip in some renderers, but not all platforms display it the same way.
Inline links vs reference-style links
Use inline links when the destination should be obvious in place:
[Markdown style examples](https://markdownmastery.com/blog/markdown-style-guide-examples)[Developer Markdown guide](https://markdownmastery.com/blog/developer-documentation-markdown-guide)
Use reference-style links when the same destination appears multiple times or when you want cleaner prose:
[docs][docs-link]
[docs-link]: https://markdownmastery.com/blog/markdown-for-developer-docs
Reference-style links are useful in long articles, README.md files, and documentation pages because they keep the body text readable while centralizing URLs. In CommonMark, reference labels are case-insensitive.
How do I link to a heading in Markdown?
Use an anchor link to jump to a heading on the same page or another page:
[Jump to the section](#how-do-i-link-to-a-heading-in-markdown)
Most platforms create the anchor from the heading text by slugifying it, which means converting it to lowercase, removing punctuation, and replacing spaces with hyphens. For example, ## API Reference often becomes #api-reference.
That said, anchor links do not work exactly the same on every platform. GitHub, GitLab, Obsidian, Notion, VS Code previews, and static site generators may generate different slugs, especially when headings contain punctuation, emojis, or duplicate text. Always test the final anchor in the destination platform.
How do relative links work in Markdown?
Relative links point to files or pages within the same site or repository. They are useful in docs because they stay portable when a project moves domains or when content is reorganized.
Examples:
[Developer docs](/docs/intro.md)[Style guide](../style-guide.md)[Markdown for docs](/blog/markdown-for-developer-docs)
Use relative URLs when the target lives in the same project. Use absolute URLs like https://markdownmastery.com/blog/content-formatting-guide-for-markdown when you want the link to work anywhere, including in shared snippets or external references.
How do I make a Markdown link open in a new tab?
Markdown itself does not provide a standard way to force a new tab. If you need that behavior, use an HTML anchor tag instead:
<a href="https://example.com" target="_blank" rel="noopener noreferrer">Open example</a>
The rel="noopener noreferrer" attribute is important for security and performance when using target="_blank".
Can I use HTML instead of Markdown links?
Yes. You can use HTML anchor tags in many Markdown environments when you need more control over the link behavior or attributes.
Example:
<a href="https://example.com" title="Open the example">Example link</a>
HTML is useful when you need target, rel, or other attributes that Markdown does not support directly. However, some platforms sanitize HTML, so test it in GitHub, GitLab, Notion, Obsidian, or your documentation site before relying on it.
How do I escape parentheses in a Markdown link?
If the URL contains parentheses, escape them with backslashes:
[File link](https://example.com/file\(1\).pdf)
For spaces and other unsafe characters in URLs, use URL encoding. For example, %20 represents a space:
[Project file](docs/My%20File.pdf)
This is especially important for file paths and generated URLs in documentation sites.
Why is my Markdown link not rendering correctly?
Common causes include:
- Missing brackets or parentheses
- Unbalanced parentheses in the URL
- A bad reference definition
- A relative path that does not match the file structure
- A platform-specific parser rule that differs from CommonMark
For example, this is invalid because the closing parenthesis is missing:
[Broken link](https://example.com/page
If a link fails, inspect the raw Markdown, test the URL directly in a browser, and compare the output in the target platform. GitHub Flavored Markdown (GFM) may behave differently from a strict CommonMark parser in edge cases.
What is the best way to write accessible link text?
The best link text is descriptive, concise, and understandable out of context. Screen readers often read links as a list, so vague phrases like “click here” or “read more” do not help users understand where a link goes.
Better examples:
- “Markdown style examples”
- “Developer Markdown guide”
- “Email support”
If the destination is an action, say so clearly. If the destination is a page, name the page or topic. This improves accessibility and makes the document easier to scan for everyone.
How do Markdown links work in GitHub README files?
In GitHub README.md files, Markdown links usually follow GitHub Flavored Markdown (GFM). Inline links, reference-style links, relative links, and anchor links are all commonly used in GitHub repositories.
Examples:
[Developer Markdown guide](https://markdownmastery.com/blog/developer-documentation-markdown-guide)[Markdown for docs](/blog/markdown-for-developer-docs)[Email support](mailto:support@example.com)
GitHub also supports anchor links to headings in README.md files, but the exact slug can differ from other platforms. If you move the same content to GitLab, VS Code, Obsidian, or Notion, recheck the anchors because each Markdown parser may generate headings differently.
How do I link to an email address in Markdown?
Use a mailto link:
[Email support](mailto:support@example.com)
You can include a subject line or body text with query parameters if needed:
[Email support](mailto:support@example.com?subject=Markdown%20question)
This is useful in contact pages, README.md files, and documentation sites.
What are reference links in Markdown used for?
Reference-style links are used to keep long documents readable and easier to maintain. Instead of repeating a long URL every time, you define it once and reuse the label throughout the document.
They are especially helpful in:
- Long tutorials
- README.md files
- Developer documentation
- Static site generators
- Content that repeats the same destination many times
Can Markdown links include titles or tooltips?
Yes. Inline links can include a title:
[Docs](https://example.com "Open the docs")
Some renderers show that title as a tooltip, but support varies. If the title matters for meaning, do not rely on the tooltip alone.
Do Markdown anchors work the same on every platform?
No. Anchor links are one of the most platform-dependent parts of Markdown.
Common differences include:
- How headings are slugified
- Whether punctuation is removed
- How duplicate headings are handled
- Whether special characters or emojis are preserved
GitHub, GitLab, Obsidian, Notion, VS Code previews, and static site generators may all produce different anchor IDs from the same heading. The safest approach is to test anchors in the final destination and avoid changing heading text after publishing.
Markdown link syntax quick cheat sheet
- Inline link:
[text](https://example.com) - Reference-style link:
[text][ref]and[ref]: https://example.com - Anchor link:
[Jump to section](#section-name) - Relative link:
[Guide](../guide.md) - Absolute URL:
[Guide](https://example.com/guide) - Mailto link:
[Email us](mailto:hello@example.com) - HTML link:
<a href="https://example.com" target="_blank" rel="noopener noreferrer">Open</a>
For more examples and formatting patterns, compare Markdown style examples with Markdown basics, then review Markdown for developer docs and Developer documentation markdown guide. If you want a broader refresher, see the Markdown cheat sheet and Plain text formatting.
Markdown links are easy to learn, but platform differences, accessibility choices, and URL formatting details still affect how they work in practice.