Markdown Links

Markdown links create clickable text that points to web pages, files, email addresses, or sections within a document. They make documentation easier to navigate while keeping the source readable and easy to maintain.

A standard Markdown link has two parts:

• Link text — the clickable text readers see.
• Destination — the URL, file path, email address, or heading the link points to.

Basic syntax

[Link Text](https://example.com)

Example

[MDConvertHub](https://mdconverthub.com)

Output

If you're new to Markdown, start with the Markdown Basics guide before learning different link types.

Inline links are the most common way to add hyperlinks in Markdown. The link text and destination URL are written together, making them easy to read and edit.

Syntax

[GitHub](https://github.com)

Example

Visit the [GitHub website](https://github.com).

Output

Use inline links when you know the destination URL and only need to reference it once. They work well for tutorials, documentation, blog posts, and README files where readability is more important than reusing the same link multiple times.

Reference links separate the link text from the destination URL. They're useful when the same link appears multiple times or when you want to keep long documents easier to read and maintain.

Example

Visit the [documentation][docs].

[docs]: https://mdconverthub.com/docs

Reference links are commonly used in GitHub README files, project documentation, and long technical guides because the URL is defined once and can be reused throughout the document.

Automatic links turn a URL or email address into a clickable link without adding custom link text. They're a good choice when you want readers to see the complete destination.

Example

<https://mdconverthub.com>

Output

Use automatic links when the full URL is important, such as documentation references, source links, or public resources that readers may want to copy directly.

Markdown also supports clickable email links. When selected, they open the user's default email application with the recipient already filled in.

Example

<support@example.com>

Or

[Email Us](mailto:support@example.com)

The mailto: format is commonly used on contact pages, documentation sites, open-source projects, and support portals where readers need a quick way to send an email.

Relative links connect files and folders within the same project instead of linking to a full web address. They're widely used in GitHub repositories because they continue working when a project is moved, cloned, or published from a different location.

Example

[Installation Guide](docs/installation.md)

Use relative links to connect README files, documentation pages, images, or other project resources without relying on absolute URLs.

You can also use relative links to connect related documentation and help readers navigate between guides.

[Markdown Lists](/markdown-lists)

Most Markdown editors automatically generate anchor links for headings. These links let readers jump directly to a specific section without scrolling through the entire document.

Example

[Jump to Installation](#installation)

## Installation

Heading links are especially useful in long guides, API documentation, and README files with multiple sections. They improve navigation and help readers find information faster. To learn how heading IDs are created, see the Markdown Headings guide.

Markdown allows you to wrap an image inside a link, making the image clickable. This technique is commonly used for project logos, badges, banners, and other visual elements that should open another page when selected.

Example

[![Logo](logo.png)](https://example.com)

Clickable images are frequently used in GitHub README files, documentation home pages, and project websites. For image syntax without links, see the Markdown Images guide.

Well-written links make documentation easier to navigate and maintain. Following a few simple practices helps readers understand where a link leads and reduces the chance of broken or confusing references.

• Use descriptive link text. Tell readers what they'll find after selecting the link.
• Avoid generic phrases. Replace "Click here" or "Read more" with meaningful text that describes the destination.
• Check every link. Verify that URLs, file paths, and heading anchors all work before publishing.
• Prefer HTTPS links. Use secure URLs whenever they're available.
• Use relative links within projects. They remain valid even if the repository or documentation moves.
• Keep link text concise. Short, descriptive links are easier to scan than long sentences.

Good

Read the [Installation Guide](/markdown-basics)

Avoid

[Click here](https://example.com)

Before publishing large documentation projects, run them through the Markdown Link Checker to find broken links, invalid URLs, and missing references.

Most Markdown link issues are caused by small syntax errors, missing characters, or incorrect file paths. Reviewing these common mistakes before publishing helps ensure every link works as expected.

Missing Closing Parenthesis#

A missing closing parenthesis prevents Markdown from recognizing the link correctly.

Incorrect

[GitHub](https://github.com

Correct

[GitHub](https://github.com)

Empty Link Text#

Every link should include meaningful anchor text. Descriptive links improve readability and help readers understand the destination before clicking.

Avoid

[](https://example.com)

Better

[Project Website](https://example.com)

Broken Relative Paths#

Relative links only work when the file path is correct. Double-check folder names and file locations before publishing your documentation.

Incorrect

[Guide](guide.md)

Correct

[Guide](docs/guide.md)

Before publishing, test external URLs, relative paths, and heading anchors to avoid broken navigation and improve the reader's experience.

Most modern Markdown editors support inline, reference, automatic, and relative links. Some platforms implement only part of the Markdown specification, so advanced link features may behave differently depending on where your content is published.

Clear, descriptive links make documentation easier to read and navigate. A quick review before publishing helps readers find information faster and reduces broken links.

• Write link text that clearly describes the destination.
• Use relative links for files within the same project or repository.
• Avoid adding multiple links in a single sentence unless they're closely related.
• Check external links regularly to make sure they still work.
• Keep link text concise so it's easy to scan.

For a quick syntax reference while writing, keep the Markdown Cheat Sheet open.