How to convert markdown inline links to reference format
- Step 1Load the Markdown — Paste the document into the editor or drop a
.md/.mdx/.markdownfile onto the tool. Paste mode wraps your text asinput.mdautomatically. - Step 2Leave Convert on Inline → Reference — The Convert dropdown defaults to
to-reference(shown as Inline → Reference). That is the direction you want — leave it. The other option, Reference → Inline, does the opposite and is documented in the reference-to-inline guide. - Step 3Run the conversion — Click Run. The converter walks the text once, numbers each distinct URL in first-seen order, and rewrites every
[text](url)to[text][n]. - Step 4Read the appended definition block — A blank line and the
[n]: urldefinitions are appended to the end of the document. Numbering follows the first appearance of each unique URL, so[1]is whatever you linked first. - Step 5Copy or download the result — Use Copy to grab the converted Markdown, or Download to save it. The output keeps the original filename with the same
.mdextension. - Step 6Validate the links afterward — Reference style makes broken links easy to spot in one block — run the link validator on the result to catch any URL that no longer resolves.
What the to-reference pass does to each link shape
Behaviour of the default Inline → Reference direction. The matcher is the literal pattern for [text](url); text is any run of non-] characters, url is any run of non-) characters.
| Input shape | Output | Notes |
|---|---|---|
[Docs](https://x.com) | [Docs][1] + [1]: https://x.com | Plain inline link → numbered reference |
[A](https://x.com) then [B](https://x.com) | [A][1] and [B][1], one [1]: def | Deduplicated by URL value — same URL, same number |
[Guide](https://x.com "Best Guide") | [Guide][1] + [1]: https://x.com "Best Guide" | Double-quote title captured into the definition |
 | ![Logo][1] + [1]: https://x.com/l.png | The ! is preserved — valid reference-image syntax |
[Wiki](https://e.org/Mercury_(planet)) | [Wiki][1]) + [1]: https://e.org/Mercury_(planet | URL with ) truncates at the first ) — see edge cases |
[Already][2] (existing reference link) | Unchanged | Reference-style links don't match the inline pattern |
Tier limits for this converter
The character-count limit (charLimit) is separate from the file-size limit — long documents can hit charLimit before file size. One file per run on Free.
| Tier | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10 |
| Pro-media | 50 MB | 20,000,000 | 50 |
| Developer | 500 MB | unlimited | unlimited |
Cookbook
Before/after pairs from real long-form Markdown. The left side is what you paste; the right side is what the to-reference pass returns.
A paragraph with three links, two of them the same URL
The most common case: a section that links the project homepage twice and a docs page once. The two homepage links collapse to one reference; the block at the bottom holds two definitions.
BEFORE: We ship via [the homepage](https://acme.dev) and document everything in [the docs](https://acme.dev/docs); see [the homepage](https://acme.dev) again. AFTER: We ship via [the homepage][1] and document everything in [the docs][2]; see [the homepage][1] again. [1]: https://acme.dev [2]: https://acme.dev/docs
Preserving a link title
Titles written with double quotes ride along into the definition because the whole url "title" run is captured (there is no ) inside it to stop the match early).
BEFORE: Read [the style guide](https://acme.dev/style "Internal Style Guide"). AFTER: Read [the style guide][1]. [1]: https://acme.dev/style "Internal Style Guide"
Mixed inline images and text links
Image syntax shares the bracket-paren shape, so images convert alongside text links. The ! is kept, producing the correct reference-image form.
BEFORE:  — see [the RFC](https://acme.dev/rfc). AFTER: ![architecture][1] — see [the RFC][2]. [1]: https://acme.dev/arch.png [2]: https://acme.dev/rfc
A long footer of references after a big article
Across a 2,000-word post with twelve outbound links (four of them repeats), you end with a compact numbered block. This is the readability payoff for long-form drafts.
AFTER (tail of the document): ...and that is the full migration plan. [1]: https://acme.dev [2]: https://acme.dev/docs [3]: https://github.com/acme/cli [4]: https://acme.dev/blog/v2 [5]: https://status.acme.dev
Links inside a fenced code block also convert
The converter is a text pass with no awareness of code fences. A sample link you wrote inside a ``` block as documentation will be rewritten too. If you do not want that, move the example out of the fence or convert before adding code samples.
BEFORE: Usage: ```md Link syntax: [label](https://example.com) ``` AFTER: Usage: ```md Link syntax: [label][1] ``` [1]: https://example.com
Edge cases and what actually happens
URL containing a closing parenthesis
TruncatedThe URL is matched as any run of non-) characters, so [Wiki](https://en.wikipedia.org/wiki/Mercury_(planet)) stops at the first ) — the definition becomes [1]: https://en.wikipedia.org/wiki/Mercury_(planet and a stray ) is left in the prose. Wikipedia disambiguation URLs and some tracking links hit this. Percent-encode the inner parens (%28 / %29) before converting, or fix the one definition by hand afterward.
An existing manual [1]: definition already in the document
CollisionGenerated reference numbers always start at 1 and ignore any reference definitions already present. If your document already had [1]: https://manual.com, you will end up with two [1]: lines and an ambiguous reference. Most renderers use the first definition. Renumber the manual one before converting, or run on a document that has no pre-existing references.
Link text that contains a closing bracket
Not matchedLink text is matched as a run of non-] characters, so [see [note]](url) won't match cleanly — nested brackets in the visible text are rare in Markdown but will leave the link inline. Flatten the bracketed text first if you need it converted.
Already reference-style links
Preserved[text][2] and [text][] are not inline links, so the to-reference pass leaves them untouched and does not renumber them. Mixing pre-existing references with newly generated ones is what causes the collision case above — convert a fully-inline document for predictable numbering.
Autolinks like <https://x.com>
PreservedAngle-bracket autolinks and bare URLs are not [text](url) syntax, so they are ignored entirely. They stay inline. There is no option to convert autolinks to references.
Single-quoted title
Preserved[text](url 'Title') works in this direction because the whole url 'Title' run is captured into the definition. Note the round trip is not symmetric: the Reference → Inline pass only recognises double-quote titles, so prefer "double quotes" if you plan to convert back.
Empty document or no inline links
ExpectedWith no [text](url) matches, the text is returned unchanged except for a trailing blank line where an empty definition block would go. No error is raised.
File over the tier limit
413 rejectedFree tier caps each file at 1 MB and 500,000 characters; a very long manuscript can exceed the character cap before the byte cap. Split the document with the splitter or upgrade for the higher ceilings (Pro 5,000,000 chars, Developer unlimited).
Links inside HTML comments
ConvertedThe pass does not skip HTML comments, so a [text](url) written inside <!-- ... --> will be rewritten. This is usually harmless but can surprise you if you parked draft links in comments — remove or escape them first.
Frequently asked questions
Why use reference-style links at all?
Two reasons. Readability: the prose keeps only [text][1], so long URLs stop interrupting sentences and Markdown diffs stay clean. Maintainability: every URL lives once in a bottom block, so a domain change or a dead link is a single edit rather than a hunt through the body.
Does it deduplicate links that point to the same URL?
Yes. Numbering keys off the URL value, so three links to https://x.com all become [..][1] and produce a single [1]: https://x.com definition. Deduplication is exact-string — https://x.com and https://x.com/ (trailing slash) count as different URLs and get different numbers.
How are the reference numbers assigned?
Sequentially, by first appearance of each unique URL. The first distinct URL the scanner meets becomes [1], the next new one [2], and so on. They are plain integers, not labels derived from the link text.
Are link titles preserved?
Yes. [text](url "Title") becomes [text][n] with the title carried into the definition: [n]: url "Title". This works because the title is captured as part of the URL segment. Double quotes round-trip cleanly; single quotes are preserved here but won't be re-parsed by the reverse direction.
What happens to image links?
They convert too.  becomes ![alt][n], the standard reference form for images, and the URL joins the definition block. The leading ! is kept.
Will links inside code blocks be converted?
Yes — the converter is a single text pass with no fence awareness, so a [label](url) written inside a fenced ``` block or inline code gets rewritten. If you document link syntax in code samples, convert before adding those samples or escape them.
Can I convert back to inline?
Yes. Switch the Convert dropdown to Reference → Inline (the to-inline mode). See the reference-to-inline guide. Be aware single-quote titles do not survive the reverse trip — use double quotes for a clean round-trip.
Does it touch autolinks or bare URLs?
No. Angle-bracket autolinks <https://x.com> and bare pasted URLs are not [text](url) syntax, so they are ignored. Only bracketed inline links convert.
What if a URL has a parenthesis in it?
It truncates at the first ). URLs like Wikipedia disambiguation links break — the definition keeps only the part before the paren. Percent-encode inner parens (%28/%29) before converting, or fix that one definition afterward.
Is anything uploaded to a server?
No. The conversion runs in your browser. On Pro+ it can auto-route to the local runner, which still processes on your own machine. Only an anonymous run counter is recorded for signed-in dashboard stats.
How big a document can it handle?
Free tier allows 1 MB and 500,000 characters per file, one file at a time. The character limit is the one most long manuscripts hit first. Pro raises it to 10 MB / 5,000,000 characters and 10 files; Developer is unlimited.
Where do the definitions get placed?
At the very end of the document, after a blank line. They are appended, not interleaved per section. If you need a per-section layout, that is not supported — the output is one consolidated block.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.