How to Add a Link in Markdown
Inline, reference, and relative links
A link in Markdown is two brackets side by side: the text in [ ], the URL in ( ), written as [text](url). That one line covers most of what you'll ever need.
The rest is knowing how to link to another file, a heading, or a reused URL, and the small mistakes that quietly break a link. This article covers all of it, with examples.
New to the syntax overall? Start with How to Write Markdown.
The five kinds of link
| Type | Syntax | When to use |
|---|---|---|
| Inline link | [text](url) | The everyday link |
| Link with a tooltip | [text](url "title") | Add hover text |
| Relative / local link | [text](path/to/file.md) | Link to another note in your folder |
| Anchor link | [text](#heading) | Jump to a heading in the same document |
| Reference link | [text][id] … [id]: url | Reuse a URL, or keep long URLs out of the prose |
All together:
Inline link:
See the [docs](https://example.com/docs).
With a tooltip:
See the [docs](https://example.com/docs "Read the docs").
Link to another note (relative to this .md):
Back to the [index](../index.md).
Jump to a heading in this document:
Skip to [Setup](#setup).
Reference style (define once, reuse):
Read the [guide][g], then the [guide][g] again.
[g]: https://example.com/guideLinking to another file or a heading
- Another file: use a relative path,
[index](../index.md), resolved relative to the.mdyou're in. This is what lets a folder of notes link to each other. See How to organize .md files for keeping those paths sane. - A heading: use an anchor, like
[Setup](#setup). The anchor is the heading, lowercased, spaces turned to hyphens. Handy for a table of contents inside a long note.
Reference-style links, for cleaner prose
When a paragraph is thick with long URLs, inline links make it hard to read. Reference style pulls the URLs out: use [text][id] where you want the link, and define [id]: url anywhere in the document. You can reuse the same [id] as many times as you like, and change the URL in one place.
Why your Markdown link isn't working
| Symptom | What happened | Fix |
|---|---|---|
| Link showed as plain text | A space between ] and ( | Put them right next to each other: ]( → ]( |
| Local link goes nowhere | Relative path written from the wrong place | It's relative to the .md file, so count folders from there |
| External link broke | Missing scheme (no https://) | Write the full URL, https://example.com |
| Anchor did not jump | The #anchor does not match the heading slug | Lowercase the heading, replace spaces with hyphens; check your renderer |
The number-one cause: a space between the ] and the (. Markdown needs them adjacent: [text](url), never [text] (url).
Writing links with NoteLoom
NoteLoom is an editor that reads and writes local .md files right in the browser. You write and fix your [text](url) links in the source or live view, and the reading view shows them as clickable links, all saved straight back to your local file.
NoteLoom won't find URLs, write the anchor text, or check whether a link is live. It opens, displays, and saves your Markdown; the links are yours to write.
How you use it: open app.noteloom.cc in Chrome / Edge / Arc, mount a local folder, then open a .md and write your links in source. Everything saves back to your disk, no cloud, no account.
FAQ
How do I add a link in Markdown?
How do I link to another Markdown file?
How do I link to a heading in the same document?
What's a reference-style link?
Why isn't my Markdown link working?
Can NoteLoom help me write links?
Can I do this with NoteLoom on my phone or in Safari?
Write and check your links in one place
Open NoteLoom in Chrome / Edge / Arc, mount a local folder, and write your [text](url) links in the source view: the reading view shows them clickable, and it all saves back to your disk. No software to install and no account to sign up for.