Markdown Syntax · Links

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/guide

Linking to another file or a heading

  • Another file: use a relative path — [index](../index.md) — resolved relative to the .md you'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 — [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 — 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 — 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.

To be clear about the boundaries: NoteLoom has no AI — it 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 → open a .md → write your links in source → save back to your disk, no cloud, no account.

Related reading

How to Write Markdown? Headings, lists, links, code — the basic syntax every beginner needs. How do you insert an image in Markdown? An image is a link with a leading ! — the syntax is nearly the same. How do you write Markdown tables? Table syntax, alignment, and breaks inside cells. How do you organize .md files? Keep notes tidy so relative links between them keep working. Online Markdown Editor Read and write local md files right in your browser.

FAQ

How do I add a link in Markdown?
Put the visible text in square brackets and the URL in parentheses, right next to each other: [text](url). No space between the closing bracket and the opening parenthesis — that space is the most common reason a link doesn't work.
How do I link to another Markdown file?
Use a relative path in the parentheses: [text](path/to/file.md), resolved relative to the .md you're writing in. If the other note is in the same folder, it's just [text](other.md); one folder up is [text](../other.md).
How do I link to a heading in the same document?
Use an anchor: [text](#heading). The anchor is usually the heading text lowercased with spaces turned into hyphens — a heading "## Getting Started" becomes [text](#getting-started). Exact rules vary by renderer, so check yours if it doesn't jump.
What's a reference-style link?
Instead of putting the URL inline, you give it a short id — [text][id] — and define the URL once, elsewhere: [id]: https://example.com. It keeps long URLs out of your prose and lets you reuse the same link by id. Great for footnote-heavy writing.
Why isn't my Markdown link working?
Usually one of: a space between ] and ( ; a relative path written from the wrong starting point (it's relative to the .md file); or a missing scheme (write https://example.com, not just example.com, for an external link). Check those three first.
Can NoteLoom help me write links?
NoteLoom opens your local .md and lets you write and fix [text](url) links in the source or live view, then saves back to your disk. It has no AI — it won't find URLs or write the link text for you; you write the links, it displays and saves your Markdown.
Can I do this with NoteLoom on my phone or in Safari?
Not for now. NoteLoom relies on the browser's File System Access API, which currently works in Chromium-based desktop browsers like Chrome, Edge, and Arc; Firefox, Safari, and mobile aren't supported yet.

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.

Open NoteLoom and try it