English العربية Português 日本語

Markdown: Markdown Link Syntax and Reference Links

Links are the backbone of the internet—in Markdown, a single syntax connects your document to the entire world.

1. What You'll Learn

2. A Documentation Engineer's Real Story

Emma is a documentation engineer at a SaaS company. She discovered that roughly 15% of links in the help docs were broken—some because filenames had changed, others because external sites had migrated. Users reported "clicking links leads to 404 pages." Worse, some links were scattered across dozens of Markdown files, taking days to fix.

Emma established link standards: all internal links use relative paths (domain-independent), and frequently-used links are defined in a reference section at the bottom of each document (one change applies everywhere). She also wrote a script to periodically scan all links for validity. Three months later, the link breakage rate dropped from 15% to 0.5%.

Inline links are the most common link format in Markdown, with intuitive syntax:

MARKDOWN 
[Display Text](URL)

[Visit GitHub](https://github.com)
Part Description Example
[Display Text] The clickable text users see [Visit Website]
(URL) The target URL (https://example.com)

(1) Adding a Title Attribute

You can add an optional title attribute after the URL (displayed on hover):

MARKDOWN 
[Google](https://google.com "Visit Google Search")

[MDN Docs](https://developer.mozilla.org "Comprehensive Web Technology Documentation")
💡 Tip: The title attribute helps slightly with SEO, but more importantly, it improves accessibility—screen readers will read out the title content.

MARKDOWN 
- [Google](https://google.com) — Search engine
- [GitHub](https://github.com "The world's largest code hosting platform") — Code hosting
- [MDN Web Docs](https://developer.mozilla.org) — Web technology documentation
MARKDOWN 
Method 1 (most common, with brackets):
[google]: https://google.com

Method 2 (shorthand without brackets):
Google: https://google.com

Method 3 (implicit link ID, auto-matches):
[Google][]
...

[Google]: https://google.com
💡 Tip: Implicit links like [Google][] auto-use the bracket text as the ID, looking up the [Google]: definition. This is convenient when link text and ID are the same.

MARKDOWN 
## Recommended Resources

For web development, check out [MDN][] and [W3Schools][].
For code hosting, try [GitHub][]; for Q&A, visit [Stack Overflow][].

## References

- [MDN][]'s CSS documentation is comprehensive
- [Stack Overflow][] has tons of frontend Q&A

[MDN]: https://developer.mozilla.org/en-US/
[W3Schools]: https://www.w3schools.com/
[GitHub]: https://github.com
[Stack Overflow]: https://stackoverflow.com/
💡 Tip: The biggest advantage of reference links is maintainability. When an external link changes, you only need to modify one line at the bottom, and all references update automatically.

In GitHub projects or local docs, use relative paths to link to other files within the same project:

TEXT 📖 Display only 
Project Documentation:

Installation Guide → installation.md
API Reference → api/overview.md
FAQ → faq.md
Previous Section → chapter-1/intro.md
⚠️ Note: Relative paths are domain-independent. On GitHub, links pointing to other files in the same repo should use relative paths, not absolute URLs—this way links remain valid after cloning or forking.

TEXT 📖 Display only 
Awesome Project

Quick Start: See docs/installation.md
Contribution Guide: Check CONTRIBUTING.md
Related Projects: Core Library (packages/core/README.md)
                 CLI Tool (packages/cli/README.md)

Wrap a URL or email address in <>, and Markdown will automatically generate a link:

MARKDOWN 
<https://example.com>
<user@example.com>

In some cases you want to display a URL without making it clickable—use code formatting or escaping:

MARKDOWN 
`https://example.com` (displayed as code, not clickable)

Or:

\*\*https://example.com\*\* displays the URL as plain text

▶ Example: Auto Link vs Plain Text URL

MARKDOWN 
Auto link: <https://www.google.com>
Plain text (no auto-link): https://www.google.com
Link with text: [Visit Google](https://www.google.com)
💡 Tip: Most parsers auto-detect URLs starting with http:// or https:// and generate links even without <>. But in standard Markdown, using <> is the explicit approach.

7. Anchor Links (In-Page Navigation)

Anchor links let users click to jump to a specific location on the same page:

MARKDOWN 
## Table of Contents

- [Introduction](#1-introduction)
- [Installation](#2-installation)
- [Configuration](#3-configuration)

---

## 1. Introduction
...
Jump to [Back to Top](#table-of-contents)
⚠️ Note: GitHub auto-converts headings to anchor IDs: Chinese characters become pinyin or Unicode; English becomes lowercase with hyphens. Check the # portion of the rendered page URL to confirm the actual anchor value.

MARKDOWN 
# Python Tutorial

## Table of Contents

- [Installing Python](#1-installing-python)
- [First Program](#2-first-program)
- [FAQ](#faq)

---

## 1. Installing Python

...

## 2. First Program

...

## ❓ FAQ

...
MARKDOWN 
# Web Development Learning Path

## Frontend Basics

| Technology | Documentation | Description |
|:-----|:-----|:-----|
| HTML | [MDN HTML][mdn-html] | Web structure |
| CSS | [MDN CSS][mdn-css] | Web styling |
| JS | [MDN JS][mdn-js] | Interactivity |

## Hands-On Projects

Refer to the [Project Template][repo] to start your first website.

## Related Content

- Check [Internal Notes](notes/frontend-roadmap)
- Join the [Community Forum][forum]
- Contact: <author@example.com>

[mdn-html]: https://developer.mozilla.org/en-US/docs/Web/HTML
[mdn-css]: https://developer.mozilla.org/en-US/docs/Web/CSS
[mdn-js]: https://developer.mozilla.org/en-US/docs/Web/JavaScript
[repo]: https://github.com/example/web-starter
[forum]: https://community.example.com

Expected result: A well-structured documentation page combining inline links, reference links, table links, and email links into a complete learning resource network.

❓ FAQ

Q How to choose between inline and reference links?
A Use inline links when a link appears only once. Use reference links when the same link appears multiple times or needs centralized maintenance.
Q How do I make links open in a new tab?
A Standard Markdown doesn't support target="_blank". You need to use HTML: <a href="url" target="_blank">Text</a>.
Q Can images have links?
A Yes. Use the nested syntax [![image alt](image src)](link url) to make clicking an image navigate to a URL.
Q Is the link title attribute important for SEO?
A It has minimal impact, but the title attribute improves accessibility. The real SEO key is making the link text itself descriptive—use "View the Installation Guide" instead of "click here."

📖 Summary

📝 Exercises

  1. Basic: Write a short article using inline links with at least 3 external references (e.g., recommend your 3 most-used online tools).

  2. Intermediate: Rewrite the above exercise using reference links. Then create a short GitHub project and use relative links to guide users from README.md to sub-pages under docs/.

  3. Challenge: Write a "Learning Resources Hub" document that combines inline links, reference links (at least 5), anchor links for table-of-contents navigation, and an email auto-link <user@example.com> at the bottom.

Web-Tutorial.com

Web-Tutorial Tech Team

A team of developers maintaining programming tutorials. Each tutorial is written and reviewed by developers with expertise in that field. We work to keep our content accurate and reliable — if you spot an issue, please let us know.

100%

🙏 帮我们做得更好

我们是刚上线的编程教程站，几个人的小团队，精力有限。页面虽经检查，难免还有疏漏——链接失效、排版错乱、内容有误、语言生硬……

如果您发现了，麻烦告诉我们，我们会在收到反馈后第一时间进行修复，再次感谢您的光临 🙏