--- title: "Markdown Links: Internal, External, Anchors & Reference-Style" description: "Master Markdown links — basic syntax, internal anchors, reference-style links, automatic linking, link titles, opening in new tabs, and SEO best practices." date: "2025-11-12" author: "Markdown Viewer Team" tags: ["markdown", "links", "syntax", "SEO"] cover: "/og.png" --- Links are how Markdown becomes the web. The basic syntax is two characters away from a working hyperlink — but if you want anchor links, reference-style organization, or links that open in a new tab, you'll need a few more tricks. This guide covers every kind of link you'll ever need to write in Markdown, with examples and a reference card at the bottom. ## The basic Markdown link The standard inline link syntax: ```md [Link text](https://example.com) ``` Two parts: - `[Link text]` — the visible, clickable text. - `(URL)` — the destination, in parentheses. Example: ```md Visit [Markdown Viewer](https://trymarkdownviewer.com) to try it. ``` You can also add a tooltip (shown on hover): ```md [Markdown Viewer](https://trymarkdownviewer.com "Free online Markdown editor") ``` The tooltip is plain HTML `title` and works in every browser. ## Automatic links If you have a bare URL, Markdown can auto-link it for you. Two ways: ```md ``` The angle-bracket form is the **CommonMark autolink** — works in every renderer. ```md Visit https://trymarkdownviewer.com to try it. ``` The bare-URL form requires **GFM autolinks** — supported by GitHub, GitLab, and most modern renderers. Don't rely on it for portable documents. ## Internal links — linking inside the same document To link to a heading **on the same page**, use a hash followed by the heading's auto-generated ID: ```md [Jump to installation](#installation) ## Installation … ``` GitHub-style renderers automatically generate IDs from heading text by: 1. Lowercasing everything 2. Replacing spaces with hyphens 3. Removing punctuation So `## Installation guide` becomes `#installation-guide`. If two headings share the same slug, the renderer adds `-1`, `-2`, and so on. Some renderers (Pandoc, MkDocs Material) let you customize the heading ID: ```md ## Installation {#install} [Jump to install](#install) ``` Markdown Viewer's preview supports this slug pattern out of the box — try it in the [editor](/editor). ## Linking to other Markdown files For a multi-file project (a docs site, a multi-page README), use **relative paths**: ```md See [the contributing guide](./CONTRIBUTING.md) for details. ``` Or to link to a specific heading in another file: ```md See [the installation steps](./SETUP.md#installation). ``` Two things to know: - Some renderers (GitHub) automatically rewrite `.md` paths to the rendered HTML route. Others (Pandoc, static site generators) keep them as-is and you need to write the rendered path yourself. - Linking with a leading slash (`/CONTRIBUTING.md`) is **absolute** — it starts at the repo root. Without the slash, it's relative to the current file. ## Reference-style links Inline links clutter prose when you have many. Reference-style links separate the URL from the text: ```md You can edit Markdown in the [browser][editor], read the [docs][guide], or clone the [GitHub repo][repo]. [editor]: https://trymarkdownviewer.com/editor [guide]: https://trymarkdownviewer.com/guide [repo]: https://github.com/saifurrahmanshochib/markdown-viewer ``` The label inside the second set of brackets matches the definition at the bottom of the document. Labels are **case-insensitive**. You can also omit the label and use the text itself: ```md Try [Markdown Viewer]! [Markdown Viewer]: https://trymarkdownviewer.com ``` Reference-style is great when: - You reuse the same link multiple times. - You're writing a long article and want the prose to stay readable. - You're collaborating and reviewers want to see what URLs were added at a glance. ## Link titles (tooltips) Both inline and reference-style links accept an optional title: ```md [Markdown Viewer](https://trymarkdownviewer.com "A free online editor") [Markdown Viewer][mv] [mv]: https://trymarkdownviewer.com "A free online editor" ``` The title is shown in a browser tooltip. It's also useful for accessibility tools that announce it as additional context. ## Open links in a new tab Pure Markdown doesn't support this. The standard solution is HTML: ```md Open in new tab ``` Always include `rel="noopener noreferrer"` for external links: - `noopener` — prevents the new page from getting access to your page via `window.opener` (a security and performance issue). - `noreferrer` — prevents the `Referer` header from being sent. Some renderers (including Markdown Viewer) automatically add these attributes to external links — check the [editor preview](/editor) for the live behavior. ## Email and phone links Markdown supports email autolinks: ```md ``` Or the inline form: ```md [Send us an email](mailto:hello@example.com) ``` You can also pre-fill the subject and body: ```md [Email us](mailto:hello@example.com?subject=Hello&body=Hi%20there) ``` Phone numbers use `tel:`: ```md [Call us](tel:+15551234567) ``` ## Anchor links to specific text (text fragments) A relatively new browser feature lets you link to **specific text** on a page using a URL text fragment: ```md [Jump to "installation"](https://docs.example.com#:~:text=installation) ``` The browser scrolls to and highlights the matching text. Works in Chrome, Edge, and Safari (Firefox is catching up). It's a great pattern for documentation links. ## Footnote links (GFM) When you want a small link in the prose with a longer note at the bottom, use footnotes: ```md Markdown was created in 2004[^1]. [^1]: By John Gruber and Aaron Swartz. ``` Footnotes are GFM and work in GitHub, Markdown Viewer, and most modern renderers. ## Links inside images (and vice versa) You can wrap an image in a link: ```md [![Alt text](/logo.png)](https://example.com) ``` Result: clickable image. This is how every GitHub README badge works. You **can't** put a link inside the alt text of an image — the alt text is plain string, not Markdown. ## Linking to a specific line of code on GitHub GitHub generates anchors for line numbers. Click any line in a file view and the URL becomes: ``` https://github.com/user/repo/blob/main/src/index.ts#L42 ``` You can also link to a range with `#L42-L57`. These deep links are gold for code reviews and bug reports. ## URL encoding for special characters URLs with spaces, parentheses, or special characters need to be encoded. The most common one: - Space → `%20` - `(` → `%28` - `)` → `%29` ```md [Search results](https://example.com/search?q=markdown%20editor) ``` Most editors handle this automatically when you paste a URL. If you're writing by hand, run the URL through `encodeURIComponent` once. ## SEO best practices for Markdown links Search engines treat Markdown links the same as HTML `` tags after rendering. To boost SEO: 1. **Use descriptive anchor text.** "Click here" is meaningless — "the Markdown table guide" is searchable. 2. **Link to canonical URLs.** Avoid linking to redirects or query-laden URLs when a clean canonical exists. 3. **Avoid cloaking.** Don't make the link text say one thing and link somewhere unrelated. 4. **Use `nofollow` for untrusted content.** User-generated links (comments, forums) should get `rel="nofollow"`. 5. **Don't open every external link in a new tab.** It's anti-UX. Reserve new tabs for contexts where leaving would lose state (forms, half-finished work). ## Common Markdown link mistakes **1. Forgetting the parentheses.** `[text]url` isn't a link — it's text followed by text. **2. Spaces between the brackets and parens.** `[text] (url)` doesn't work in strict CommonMark. Always: `[text](url)`. **3. Reversed syntax.** Some users remember it as `(text)[url]` (the bracket order is wrong). Markdown uses `[text](url)` — same order as a function call. **4. Unencoded URLs.** A space in the URL breaks the link. **5. Heading anchor case mismatch.** `#Installation` won't find a heading rendered as `#installation`. Lowercase the slug. **6. Linking with the heading text instead of the slug.** `[Jump](#My Heading)` doesn't work — use `[Jump](#my-heading)`. ## Link best practices - **One purpose per link.** Don't pack two destinations into one anchor. - **Open in same tab by default.** Users know how to middle-click. - **Front-load the keyword.** "Read the [installation guide]" reads better than "click [here] for installation". - **Don't end sentences with links.** It's harder to scan visually. - **Validate links periodically.** Use [Markdown Viewer's link checker](/editor) — open the Links tab in the sidebar and click **Check**. ## Try it now Open the [Markdown editor](/editor) and try each style of link. The toolbar's link button (Ctrl/⌘ + K) inserts the `[text](url)` skeleton and selects the URL portion so you can paste immediately. ## Related articles - [Markdown cheat sheet](/blog/markdown-cheat-sheet) — every Markdown feature on a single page - [How to add images in Markdown](/blog/markdown-images-guide) — alt text, sizing, hosting - [Markdown syntax guide](/blog/markdown-syntax-guide) — CommonMark and GFM, end to end ## Quick reference ```md [Inline](url) Inline link [Inline](url "Title") With tooltip [Reference][label] Reference-style [label]: url "Title" Reference definition Autolink (CommonMark) [Jump](#heading-slug) Internal anchor [Doc](./other.md#section) Cross-file link [Email](mailto:hi@example.com) Email link [Call](tel:+15551234567) Phone link [![alt](img.png)](url) Clickable image [^1] Footnote ref [^1]: Footnote text Footnote definition ``` The link is the smallest unit of the web — and Markdown gives you eight different ways to write one.