Markdown Links

Basic Link Syntax

The standard way to create a link in Markdown is the inline syntax: put the link text in square brackets, followed immediately by the URL in parentheses. No space between the ] and (.

Visit [GitHub](https://github.com) for open-source projects.

Read the [CommonMark spec](https://commonmark.org) for the full syntax reference.

The syntax is [visible text](destination URL). Square brackets hold what the reader sees; parentheses hold where the link goes.

Link with Title

Add a title attribute by placing quoted text after the URL inside the parentheses. The title appears as a tooltip when the reader hovers over the link.

[MDViewer](https://getmd.ma "MDViewer — native Markdown viewer for macOS")

The title must be enclosed in double quotes, single quotes, or parentheses. Double quotes are the most common convention. A space separates the URL from the title string.

Reference-Style Links

Reference-style links separate the link text from the URL. You place a label in a second set of brackets, then define that label anywhere in the document. This keeps your paragraphs clean and makes it easy to reuse the same URL.

I use [GitHub][gh] for version control and [GitLab][gl] for CI pipelines.

[gh]: https://github.com
[gl]: https://gitlab.com

If the label matches the link text, you can use an empty second bracket or omit it entirely:

Visit [GitHub][] for open-source projects.

[GitHub]: https://github.com

Reference definitions do not appear in the rendered output. They can go anywhere in the file, but placing them at the bottom is the most common convention.

Auto-Links

Wrap a URL or email address in angle brackets to turn it into a clickable link without custom text. The URL itself becomes the link text.

<https://getmd.ma>
<support@example.com>

In GitHub Flavored Markdown (GFM), bare URLs are automatically linked without angle brackets. Just type the full URL and it becomes clickable:

Check out https://github.com for more details.

Bare URL auto-linking is a GFM extension. Strict CommonMark processors require angle brackets. When in doubt, use <url> for maximum compatibility.

Anchor Links (Jump to Section)

Link to a heading on the same page using #heading-id as the URL. Most Markdown renderers generate heading IDs automatically by converting the heading text to lowercase and replacing spaces with hyphens.

[Jump to Installation](#installation)

## Installation
...your content here...

To build a table of contents, list anchor links at the top of your document:

**Table of Contents**
- [Getting Started](#getting-started)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

ID generation rules differ slightly by platform. GitHub strips punctuation and collapses consecutive hyphens. Obsidian preserves more characters. When in doubt, keep heading text simple and check the generated ID in your renderer.

Relative Links

Link to other files in the same repository using relative paths. This keeps links working when the repo is cloned, forked, or moved to a different host.

See the [Setup Guide](./docs/setup.md) for installation steps.
Go back to the [README](../README.md).

You can also combine a relative path with an anchor to link to a specific section in another file:

[Environment variables](./docs/config.md#environment-variables)

Use ./ for the current directory and ../ to go up a level. GitHub, GitLab, and most desktop Markdown editors resolve relative links correctly.

Images as Links

Wrap an image in a link by nesting the image syntax inside the link’s square brackets. The image becomes clickable.

[![Project logo](./images/logo.png)](https://github.com)

The pattern is [![alt text](image-url)](link-url). The outer [] holds the image (which serves as the link text), and the outer () holds the destination URL. This is commonly used for badges in README files:

[![Build Status](https://img.shields.io/github/actions/workflow/status/user/repo/ci.yml)](https://github.com/user/repo/actions)

Open in New Tab

Standard Markdown has no syntax for opening a link in a new tab. To get this behavior, use inline HTML with target="_blank".

<a href="https://github.com" target="_blank" rel="noopener">Open GitHub in a new tab</a>

Always include rel="noopener" alongside target="_blank" for security. This prevents the opened page from accessing your page’s window.opener object.

Keep in mind that some platforms strip HTML attributes for security. GitHub README files, for example, remove target="_blank". This workaround is most useful when you control the Markdown renderer, such as in a static site generator, a wiki, or a desktop app like MDViewer.

Platform Support

Not every link syntax works on every platform. This table shows what you can rely on.

* GitHub strips target attributes from rendered Markdown for security. The link still works but opens in the same tab.

Common Mistakes

Forgetting the protocol

A link without https:// is treated as a relative path, not an external URL. The result is a broken link pointing to a file in your repository.

[Site](https://example.com)   <-- correct
[Site](example.com)           <-- broken, missing https://

Space between brackets and parentheses

Adding a space between ] and ( breaks the link. The closing bracket and opening parenthesis must be adjacent.

[GitHub](https://github.com)    <-- works
[GitHub] (https://github.com)   <-- broken, space between ] and (

Wrong bracket order

Swapping the brackets and parentheses — putting the URL in square brackets and the text in parentheses — produces literal text instead of a link.

[Click here](https://example.com)    <-- correct
(Click here)[https://example.com]    <-- wrong order, renders as plain text

Parentheses in URLs

URLs that contain parentheses (like Wikipedia links) break the syntax because Markdown sees the first ) as the end of the URL. Escape inner parentheses with \ or use angle brackets:

[Markdown](https://en.wikipedia.org/wiki/Markdown_(software\))

[Markdown](<https://en.wikipedia.org/wiki/Markdown_(software)>)

FAQ

How do I make a clickable link in Markdown?

Use the inline link syntax: [link text](https://example.com). The text inside the square brackets becomes the clickable text, and the URL inside the parentheses is the destination. For example, [Visit GitHub](https://github.com) renders as a clickable “Visit GitHub” link.

Can Markdown links open in a new tab?

Standard Markdown does not support opening links in a new tab. You need to use raw HTML: <a href="https://example.com" target="_blank" rel="noopener">link text</a>. Most Markdown processors that allow inline HTML will render this correctly. Some platforms like GitHub strip the target attribute for security reasons.

What is a reference-style link?

A reference-style link separates the link text from the URL. You write [link text][id] in the body, then define [id]: https://example.com elsewhere in the document. This keeps paragraphs readable and lets you reuse the same URL in multiple places without repeating it.

How do I link to another file in the same repo?

Use a relative path: [Setup Guide](./docs/setup.md) or [README](../README.md). Relative links work on GitHub, GitLab, and most Markdown renderers. Use ./ for files in the same directory and ../ to go up a level. This keeps links working even when the repository is cloned or forked.

Do Markdown links work in all apps?

Inline links [text](url) work in every Markdown processor. Reference-style links are supported nearly everywhere. Auto-links with angle brackets are part of the CommonMark spec. Bare URL auto-linking depends on the platform — GitHub and most modern editors support it, but strict CommonMark processors do not.

How do I add an anchor link in Markdown?

Link to a heading on the same page with [text](#heading-id). The heading ID is generated automatically: convert the heading text to lowercase, replace spaces with hyphens, and remove punctuation. For example, ## Getting Started becomes #getting-started. Use [Jump to Getting Started](#getting-started) to link to it.

Preview Your Markdown Links with MDViewer

MDViewer is a native macOS app that renders your Markdown files instantly. Links in your documents are fully clickable in the preview — external URLs open in your browser, relative links navigate between files, and anchor links jump to the right section. Double-click any .md file in Finder and see every link working exactly as your readers will.

Requires macOS 13.0 or later. Intel and Apple Silicon.