Markdown Links and Images: Inline vs Reference Style, and When to Use Each
Quick answer
Inline links and images put the destination right next to the text: [link text](url) and . Reference-style links and images use a short identifier in the text — [link text][id] — and resolve it against a definition placed separately, usually near the bottom of the document. Both compile to identical HTML. The choice affects how readable and maintainable your raw Markdown stays — not how the page renders.
Reach for inline when a document is short or the link is a one-off. Save reference style for long documents, dense citations, or a URL you'll reuse more than once — John Gruber's original rationale was readability of the source itself, not ease of typing.
How it actually works
Inline syntax
Inline is the syntax most people learn first. Wrap the visible text in square brackets, then put the destination in parentheses immediately after:
[Carets on the App Store](https://apps.apple.com/app/carets)
An optional title can follow the URL in quotes. GitHub's own docs describe the same pattern: wrap the link text in brackets, then wrap the URL in parentheses. Images are link syntax with a leading ! — everything else works the same way.
Reference syntax
Reference style splits the link into two pieces. The in-text part is a bracketed identifier:
Read the [CommonMark spec][spec] before you argue about Markdown flavors.
[spec]: https://spec.commonmark.org/0.31.2/ "CommonMark 0.31.2"The definition — label, colon, URL, optional title — can live anywhere in the document, before or after the text that references it, as long as it doesn't interrupt a paragraph. CommonMark's tutorial puts it plainly: this keeps the body text cleaner and lets you reuse the same reference more than once.
The CommonMark spec formalizes three reference forms:
- Full reference:
[link text][id]— text and identifier differ. - Collapsed reference:
[id][]— text and identifier are the same, so the second bracket pair is left empty. - Shortcut reference:
[id]— no second bracket pair at all; Markdown resolves it against a matching definition.
Label matching is case-insensitive, and if the same label is defined twice, the first definition wins. Reference-style images follow an identical pattern with the ! prefix: ![alt text][id], defined the same way as a link reference.
Why reference style exists
Gruber's own explanation is worth quoting directly: "The point of reference-style links is not that they're easier to write. The point is that with reference-style links, your document source is vastly more readable." Moving the URL out of the paragraph keeps long or ugly links from interrupting the sentence you're actually trying to write — and a definition, once written, can back multiple in-text references without retyping the URL.
When to use it (and when to skip it)
Use inline when:
- The document is short — a quick note, a single scratch file, a one-off README fix.
- The link appears exactly once and you're not going to reuse it.
- You want the destination visible at the point of use, with no scrolling to check where an identifier points.
Use reference style when:
- The document is long and dense with citations — the kind of piece where keeping headings navigable already matters for the same reason: readers and writers both benefit when structure stays out of the way of the prose.
- The same URL shows up more than once. Define it once, reference it as many times as you need.
- You're tracking changes in version control. A URL edit touches one definition line instead of every place the link appears in the body, which keeps diffs small and reviewable.
Most real documents mix both. Use inline for a casual aside or a single link that doesn't need reuse, and reference style for the citations and repeated destinations that matter. One limitation both styles share: Markdown has no native syntax for image dimensions. If you need to control size, Gruber notes that a raw HTML <img> tag is the documented fallback.
Frequently Asked Questions
What's the difference between inline and reference-style links in Markdown?
Inline links put the URL right after the link text in parentheses — [text](url). Reference-style links put a short identifier after the link text — [text][id] — and define the actual URL separately, usually near the bottom of the document or section.
Does reference-style Markdown render any differently than inline?
No. Both compile to the same HTML anchor or image tag. The difference is entirely in the source — how easy the raw Markdown is to read and maintain — not in the output.
When should I use reference-style links instead of inline?
Reach for reference style when a document is long, cites several sources, or reuses the same URL more than once. It keeps paragraphs free of long URLs and lets you update a link in one place. For a short note or a single one-off link, inline is faster and just as clear.
Can I mix inline and reference-style links in the same document?
Yes. CommonMark and GitHub Flavored Markdown both parse them side by side with no conflict. Many long-form writers use inline for quick asides and reference style for citations or repeated links.
Does image syntax work the same way as link syntax?
Yes — image syntax is link syntax with a leading exclamation mark. Inline is , reference style is ![alt text][id] with the URL defined separately. The same inline-vs-reference trade-offs apply.
How Carets fits in
Carets edits plain Markdown, so both of these syntaxes render exactly as written — no proprietary rich-text layer quietly rewriting your link definitions or collapsing your reference list. Files, projects, and tags keep long, reference-heavy documents organized instead of buried in one folder, and syntax highlighting makes it easy to spot a mismatched reference identifier before it breaks.
If your writing workflow already leans on a plain-text capture-and-organize system, reference-style links are a natural extension of the same habit: keep the prose clean, keep the structure — definitions, tags, files — out of the way until you need it. Carets is native and fast on iPhone, iPad, and Mac, and your files stay plain text, so nothing you write today locks you into one app tomorrow.
Carets is available on the App Store for iPhone, iPad, and Mac.