How to Embed Links in Markdown | Syntax That Works

Markdown links use [visible text](URL); add a quoted title or use reference links for repeated URLs.

A broken bracket can turn a polished README into plain text; learning how to embed links in Markdown means pairing the words readers see with the address they should open. The core pattern is small, but spacing, titles, anchors, and reference links decide whether the link renders or sits there as raw characters.

Use inline links for most writing. Use reference links when the same destination appears more than once, or when long URLs make a paragraph hard to read.

Embedding Links In Markdown Without Broken Syntax

Markdown inline links put the clickable text in square brackets and the destination in parentheses, with no space between the closing bracket and opening parenthesis. The rendered page shows only the bracketed text as the clickable link.

Read the [project docs](https://example.com/docs) before editing.

That line renders as a sentence where “project docs” is clickable. The URL can be a full web address, a relative path, or a section anchor, depending on where the Markdown file will be published.

For a title that appears when a reader hovers over the link in many renderers, place quoted text after the URL inside the same parentheses.

[Project docs](https://example.com/docs "Project documentation")

The hover title is optional. Skip it when the visible link text already describes the destination.

Which Markdown Link Format Should You Use?

Inline links fit short, one-off links; reference links fit repeated links and long URLs. Autolinks and relative links have narrower jobs, so reserve them for the cases where they make the file easier to maintain.

Write Reference Links When One URL Repeats

Reference links move the URL to a definition line, which keeps crowded paragraphs readable. The visible text stays in the sentence, while the destination sits elsewhere in the document.

Read the [setup notes][setup] before changing the config.

[setup]: https://example.com/docs/setup "Setup notes"

The label inside the second pair of brackets must match a definition label. CommonMark says link text uses square brackets and inline destinations use parentheses; CommonMark’s link tutorial also shows reference links with the destination placed near the bottom of the text.

Reference labels are not case sensitive in CommonMark, but matching the same spelling every time reduces mistakes when another person edits the file. Place the definition near the paragraph for short files or near the bottom for long files.

Add Email, File, And Section Links

Markdown destinations can point to email addresses, project files, or page sections when the renderer accepts those destinations. The bracket-and-parenthesis pattern does not change.

• Email link: [Email the team](mailto:hello@example.com)
• File in the same folder: [Changelog](CHANGELOG.md)
• File in another folder: [Install notes](docs/install.md)
• Root-relative page: [Pricing](/pricing/)
• Heading on the same page: [Setup](#setup)

Heading anchors vary by renderer. GitHub, static site builders, and CMS plugins may convert spaces, punctuation, and capital letters differently, so preview the published page before you rely on a jump link.

Why Do Markdown Links Break?

Markdown links usually fail because one character is missing, misplaced, or interpreted differently by the renderer. The fastest fix is to compare the broken link with the exact pattern it was meant to follow.

Test Links Before You Publish

A link check before publishing catches mistakes that a Markdown preview can hide, especially when files move between GitHub, a static site builder, and a CMS. Test in the renderer that will display the final page, not only in your editor.

1. Open the Markdown file in the target preview.
2. Click every inline link, reference link, email link, and anchor link.
3. Move or rename one linked file only after checking every relative path that points to it.
4. Change a heading only after checking anchor links that point to that heading.
5. Scan for spaces between ] and (, because that tiny gap breaks many inline links.

Every linked phrase should open the chosen page, file, email draft, or section jump without showing raw Markdown syntax.

Copy The Pattern That Matches The Link

The dependable move is to match the link type to the destination, then preview it in the renderer that will publish the file. Most Markdown link problems disappear when the syntax and destination type match.

• For one normal web link, type [visible text](https://example.com).
• For one link with hover text, type [visible text](https://example.com "Title text").
• For repeated URLs, type [visible text][label] in the sentence and [label]: https://example.com near the bottom.
• For a clickable email address, type [Email name](mailto:name@example.com).
• For a same-site page or file, type a relative destination such as [Docs](docs/index.md).
• For a clickable image, type [![Alt text](image.png)](https://example.com).

After pasting the pattern, render the file once and click the finished link. The clickable text should appear normally, and the raw brackets should be gone.

Send us your feedbackTell us what you thought about this post

Name * Email *

Your comment *

Quick check — what is …? *

Send feedback