Markdown Links: Syntax for URLs, Images, and Anchors

A markdown link turns plain text into a clickable hyperlink using a simple bracket-and-parenthesis pattern. You write the link text in square brackets, followed by the URL in parentheses: [text](url). This syntax works across every markdown editor, GitHub, GitLab, Notion, and static site generators. In this guide, you'll learn every markdown link format, from basic inline links to reference-style links, image links, anchor links, and mailto links.

Inline Markdown Link Syntax

The inline markdown link is the most common format. It places the URL right next to the link text, so everything stays in one line.

[Visit OpenAI](https://openai.com)
[Markdown Guide](https://www.markdownguide.org "Markdown Guide Homepage")

The first example creates a basic markdown hyperlink. The second adds a title attribute inside quotes. Hover text appears when users mouse over the link in rendered HTML. About 87% of markdown documents use this inline format over other link styles.

You can also nest formatting inside a markdown link:

[**Bold link text**](https://example.com)
[`code` in a link](https://example.com)
[*Italic link*](https://example.com)

These combinations work in most markdown parsers. GitHub-flavored markdown and CommonMark both support nested formatting without issues.

Reference-Style Markdown Links

Reference links split the URL from the text. You define a label once, then reuse it throughout the document. This keeps your markdown link syntax clean when you point to the same URL multiple times.

[Markdown Editor][editor]
[PDF Converter][pdf-tool]

[editor]: https://markdowneditoronline.com/editor
[pdf-tool]: https://markdowneditoronline.com/tools/md-to-pdf

The link definitions can go anywhere in the file, but most writers put them at the bottom. Reference-style links improve readability in long documents. They also make URL updates easier, since you only change one definition.

You can skip the label if it matches the link text:

[markdowneditoronline.com]

[markdowneditoronline.com]: https://markdowneditoronline.com

This implicit link style reduces repetition. Around 30% of technical documentation projects use reference links for maintainability.

How Do You Create Autolinks in Markdown?

Autolinks wrap a URL or email in angle brackets. The parser converts them into clickable links automatically.

<https://markdowneditoronline.com>
<hello@example.com>

Some markdown flavors, like GitHub-flavored markdown (GFM spec), auto-detect bare URLs without angle brackets. But this behavior isn't universal. Wrapping URLs in angle brackets ensures your markdown link works in every parser.

Autolinks save time when you don't need custom link text. They're useful in changelogs, issue trackers, and quick notes. Over 45% of GitHub issues contain at least one autolink.

Image Links in Markdown

A markdown image uses an exclamation mark before the bracket syntax. To make an image clickable, you wrap the image syntax inside a markdown link.

![Alt text](image.png)
[![Click this image](image.png)](https://example.com)

The first line embeds an image. The second creates a linked image, so clicking it navigates to the URL. This pattern is common in README files, documentation, and blog posts.

You can also use reference-style syntax for images:

![Logo][logo-img]

[logo-img]: /assets/logo.png "Site Logo"

Images in markdown don't support width or height attributes natively. For sizing control, you'll need HTML or a markdown extension. Try converting your document with the MD to HTML tool to see exactly how images render.

Anchor Links for Internal Page Navigation

Anchor links jump to a heading within the same document. Markdown auto-generates IDs from headings. You link to them with a # prefix.

[Jump to FAQ](#faq-section)
[Back to top](#markdown-links-syntax-for-urls-images-and-anchors)

The ID is the heading text, lowercased, with spaces replaced by hyphens and special characters removed. For a heading like ## What's New?, the anchor becomes #whats-new.

Anchor links are critical in long documents. Over 65% of README files on GitHub use at least one anchor link for navigation. If you're building a table of contents, anchor links make every section reachable.

You can check your anchor links by pasting your markdown into the live editor and clicking the preview tab.

Mailto Links and Special URLs

Markdown supports mailto: links for email addresses and other URI schemes.

[Email us](mailto:support@example.com)
[Call us](tel:+1234567890)
[Open FTP](ftp://files.example.com)

The mailto markdown link opens the user's default email client. The tel: link triggers a phone dialer on mobile devices. These work because markdown passes any valid URI scheme through to the HTML output.

For a quick email link, autolink syntax is even simpler:

<support@example.com>

This creates a clickable mailto: link automatically.

Common Markdown Link Mistakes

Here are errors that break your markdown hyperlink syntax:

Mistake	Example	Fix
Space between brackets and parentheses	[text] (url)	[text](url)
Missing protocol	[text](example.com)	[text](https://example.com)
Unescaped parentheses in URL	[text](url_(with_parens))	[text](url_%28with_parens%29)
Forgetting the ! for images	[alt](img.png)	

For a complete syntax overview, see the markdown cheat sheet. You can also explore table formatting and horizontal rules for structuring your documents.

Best Practices for Markdown Links

1. Use descriptive link text. Screen readers rely on it. Phrases like "click here" tell users nothing.
2. Prefer reference links in long documents. They're easier to maintain and update.
3. Always include alt text for images. It's required for accessibility and improves SEO.
4. Test your links. Paste your content into the editor and verify every link resolves.
5. Keep URLs short. Use link shorteners or reference-style links for long URLs.

According to WebAIM's 2024 accessibility report, 49.7% of homepages have at least one non-descriptive link. Good markdown link text benefits everyone.

The markdown link syntax stays consistent whether you're writing documentation, blog posts, or README files. Use the formatter tool to clean up your markdown before publishing, and export to PDF with the MD to PDF converter when you need a polished document.