Links make a README.md file more useful by connecting readers to documentation, live demos, source files, issue trackers, headings, images, and external resources. Since README files are usually written in Markdown, you can create hyperlinks with simple, readable syntax that works on GitHub and most other Markdown-supported platforms.
Whether you want to add a basic inline link, reuse links with reference-style syntax, jump to a section inside the same README, or make an image or badge clickable, Markdown provides straightforward options. Learning these patterns helps keep your README clear, organized, and easy for visitors to navigate.
As an Amazon Associate I earn from qualifying purchases.
Markdown Link Syntax Basics
Markdown links use a simple pattern: the text readers click goes in square brackets, and the destination URL goes in parentheses. The basic format is [link text](URL). For example, GitHub displays as a clickable link labeled “GitHub.” This is the most common way to add a hyperlink in a README.md file because it is short, readable, and supported by GitHub, GitLab, Bitbucket, npm, PyPI, and most Markdown renderers.
The link text should describe where the link goes or what action it supports. Instead of writing click here, use meaningful text such as [View the installation guide](docs/installation.md) or Download the latest release. Descriptive link text makes your README easier to scan, improves accessibility for screen reader users, and helps maintainers understand the purpose of each link without opening it.
#1 Best Overall
- Easily store and access 1TB to content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop. Reformatting may be required for Mac
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Basic Markdown link formats
| Link type | Markdown syntax | Common use |
|---|---|---|
| External link | [GitHub](https://github.com) |
Linking to websites, documentation, demos, or downloads |
| Relative file link | [Contributing](CONTRIBUTING.md) |
Linking to another file in the same repository |
| Folder link | [Examples](examples/) |
Linking to a directory in the project |
| Email link | [Contact us](mailto:[email protected]) |
Opening a new email message |
| Heading link | [Installation](#installation) |
Jumping to a section inside the same README |
URLs can be absolute or relative. An absolute URL includes the full address, such as https://example.com/docs. A relative URL points to a file or folder based on the current README location, such as docs/setup.md or ../assets/logo.png. Relative links are especially useful in repositories because they usually continue to work when the project is cloned, forked, or viewed on different branches.
You can also add an optional title to a Markdown link by placing quoted text after the URL: Project docs. Some Markdown renderers show this title as a toolwhen the pointer hovers over the link. Use titles sparingly because they are not always visible on mobile devices and are not a substitute for clear link text. For most README files, readable labels, correct paths, and consistent formatting are more useful than extra hover text.
Adding an Inline Hyperlink
An inline hyperlink is the most direct way to add a clickable link in a README.md file. You write the visible link text in square brackets, followed immediately by the destination URL in parentheses. This format works well on GitHub, GitLab, Bitbucket, npm, and most Markdown-supported documentation tools.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsThe basic syntax looks like this:
[link text](https://example.com)
For example, if you want to link to the official GitHub documentation, you can write:
[GitHub Docs](https://docs.github.com)
When rendered, this appears as a clickable link labeled GitHub Docs. The words inside the square brackets should describe where the link goes. Instead of writing vague text such as click here, use meaningful text like installation guide, API documentation, or project demo. This makes your README easier to scan and more accessible for people using screen readers.
Linking to project resources
Inline links are commonly used in README files to point readers to setup instructions, live demos, issue trackers, package pages, and external documentation. For example:
[View the live demo](https://example.com/demo)[Report a bug](https://github.com/username/project/issues)[Read the API documentation](https://example.com/docs)[Install from npm](https://www.npmjs.com/package/package-name)
You can also use inline links with relative paths when linking to files inside the same repository. This is useful when your README references other Markdown files, license files, examples, or source folders. For example, [Contributing Guide](CONTRIBUTING.md) links to a file named CONTRIBUTING.md in the same directory as the README. To link to a file in a subfolder, use a path such as [Configuration example](examples/config.md).
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Adding optional title text
Markdown also supports optional title text for inline links. The title appears as a toolin some browsers when a user hovers over the link. Add it inside the parentheses after the URL, wrapped in quotes:
[GitHub Docs](https://docs.github.com "Official GitHub documentation")
This feature can add context, but it should not be required for understanding the link. Many users on mobile devices or assistive technologies may never see hover text, so keep the visible link text clear on its own.
Rank #2
- Ultra Slim and Sturdy Metal Design: Merely 0.4 inch thick. All-Aluminum anti-scratch model delivers remarkable strength and durability, keeping this portable hard drive running cool and quiet.
- Compatibility: It is compatible with Microsoft Windows 7/8/10, and provides fast and stable performance for PC, Laptop.
- Improve PC Performance: Powered by USB 3.0 technology, this USB hard drive is much faster than - but still compatible with - USB 2.0 backup drive, allowing for super fast transfer speed at up to 5 Gbit/s.
- Plug and Play: This external drive is ready to use without external power supply or software installation needed. Ideal extra storage for your computer.
- What's Included: Portable external hard drive, 19-inch(48.26cm) USB 3.0 hard drive cable, user's manual, 3-Year manufacturer warranty with free technical support service.
Using full URLs correctly
For external websites, include the complete URL with https:// or http://. Writing [Example](www.example.com) may not behave as expected because Markdown can treat it like a relative path instead of an external website. A safer version is [Example](https://www.example.com).
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →If the URL contains spaces, replace them with encoded characters such as %20, or use a cleaner URL if one is available. For long URLs with special characters, test the rendered README after saving it to make sure the link opens the intended page.
Good inline link habits
- Use descriptive link text that tells readers what they will open.
- Prefer
https://links for external websites when available. - Use relative links for files within the same repository so they continue to work if the repository is moved or forked.
- Avoid placing too many links in one sentence, since it can make the README harder to read.
- Check links after publishing, especially links to demos, generated documentation, and renamed files.
Inline hyperlinks are ideal when a link appears naturally in a sentence or short list. For example: See the [installation guide](docs/installation.md) before running the project locally. This keeps the README readable in plain text while still producing a clean clickable link when Markdown is rendered.
Using Reference-Style Links
Reference-style links are useful when your README.md has several links or when you want the main text to stay clean and easy to read. Instead of placing the full URL directly inside a sentence, you use a short label in the paragraph and define the actual URL somewhere else in the file. This works well for project documentation, installation guides, API references, and long README files where repeated inline links can become distracting.
The basic format has two parts: the clickable text in the content, and the reference definition elsewhere in the Markdown file. In the paragraph, write the link text in square brackets, followed by another pair of square brackets containing the reference label. Then, usually near the bottom of the README, define that label with the URL.
Recommended Free Tools
Read the [GitHub documentation][github-docs] before contributing.
[github-docs]: https://docs.github.com/
When rendered, “GitHub documentation” becomes a clickable hyperlink. The label github-docs connects the visible link to the URL definition. The label is not shown to readers; it only helps Markdown know which URL to use. Labels can contain letters, numbers, spaces, and hyphens, but it is best to keep them short, lowercase, and descriptive.
Using Reference Links for Repeated URLs
Reference-style links are especially helpful when the same URL appears mulle times. For example, if your README mentions your project website in several sections, you can define the URL once and reuse the same reference label wherever needed.
Visit the [project website][site] for details.
You can also find examples on the [project website][site].
[site]: https://example.com
This makes maintenance easier. If the project website changes later, you only update the URL in one place instead of searching through the whole README for every occurrence.
Rank #3
- Easily store and access 4TB of content on the go with the Seagate Portable Drive, a USB external hard drive.Specific uses: Personal
- Designed to work with Windows or Mac computers, this external hard drive makes backup a snap just drag and drop
- To get set up, connect the portable hard drive to a computer for automatic recognition no software required
- This USB drive provides plug and play simplicity with the included 18 inch USB 3.0 cable
- The available storage capacity may vary.
Adding Optional Link Titles
You can also add an optional title after the URL. Some Markdown renderers show this title as hover text when a user moves the cursor over the link. GitHub supports this syntax, although hover behavior may vary by browser and platform.
See the [release s][releases] for version history.
[releases]: https://github.com/example/project/releases "Project release notes"
The title should add useful context, not repeat the link text word for word. For example, “Project release notes” is clearer than simply “Click here.”
Shortcut Reference Links
Markdown also supports a shorter form when the link text and reference label are the same. This can be convenient for familiar names such as GitHub, npm, Docker, or Python.
Free tools Windows power users keep installed
One-click scans. No signup required.
This project uses [Docker] for local development.
[Docker]: https://www.docker.com/
In this example, [Docker] automatically matches the reference definition named Docker. While this syntax is compact, explicit labels such as [Docker][docker] can be clearer in longer README files.
Best Practices for Reference-Style Links
- Place definitions consistently: Put reference definitions at the end of the README or at the end of the related section.
- Use meaningful labels: Choose labels like
install-guide,api-docs, orlicenseinstead of vague labels likelink1. - Avoid broken references: Every label used in the text must have a matching definition.
- Keep URLs updated: Reference-style links make updates easier, but outdated links can still confuse users.
- Be consistent: Use either inline links or reference-style links in a section unless mixing them improves readability.
Reference-style links are not required for every README, but they are a strong choice when you want cleaner paragraphs and easier link maintenance. For small files, inline links are often enough. For larger documentation, reference-style links help keep the Markdown organized while still producing the same clickable links for readers on GitHub and other Markdown-supported platforms.
Linking to Headings Within the README
README files often grow beyond a few paragraphs, especially in projects with installation steps, configuration details, usage examples, API s, and troubleshooting sections. Links to headings let readers jump directly to a specific part of the same README. On GitHub, GitLab, Bitbucket, and many other Markdown renderers, headings automatically receive anchor IDs that you can link to with a hash symbol, such as #installation or #usage.
The basic pattern is to create a normal Markdown link where the destination starts with #. For example, if your README has a heading called ## Installation, you can link to it like this: [Go to installation](#installation). When a user clicks the link, the page scrolls to the Installation section. This is useful near the top of the README, where many projects include a small table of contents.
Example table of contents
A simple README table of contents might look like this:
## Contents
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)
## Installation
Steps for installing the project.
## Usage
Examples of how to run the project.
Heading links are usually generated from the heading text by converting letters to lowercase, replacing spaces with hyphens, and removing most punctuation. For example, ## Getting Started becomes #getting-started, and ## Common Questions becomes #common-questions. A link to those sections would be written as [Getting Started](#getting-started) and [Common Questions](#common-questions).
Rank #4
- 【Versatile Storage Expansion – For Gaming, Work & Everyday Use】 Running out of space on your PS5 or Xbox Series X/S? This external hard drive lets you store and play PS4 / Xbox One games directly, instantly freeing up your console’s internal storage for next‑gen titles. At the same time, it handles work file backups, media libraries, and cross‑device data transfers with ease. One drive, all your needs. *（Note: PS5 / Xbox Series X|S games cannot be run or stored directly from the external hard drive. However, by offloading your PS4 / Xbox One games, you can free up valuable space for newer titles.）*
- 【Patented Silicone Sleeve – Data Protection You Can Count On】 Worried about drops? We’ve got you covered. The patented built‑in silicone sleeve acts like a shock‑absorbing armor, cushioning your drive against bumps and falls. Whether it’s important work documents, precious family photos, or hard‑earned game saves, your data deserves this level of protection.
- 【Plug & Play, Compatible with Computers & Consoles】 No complicated setup—just plug in and go. Works seamlessly with Windows, Mac, and Linux computers, as well as PS4, PS5, Xbox One, and Xbox Series X/S. Process files at the office, back up data at home, or enjoy gaming in your downtime—one drive handles all your devices, simply and hassle‑free.
- 【USB 3.0 Ultra‑Fast Transfer – No More Waiting】 Tired of watching progress bars crawl? With USB 3.0 speeds up to 5Gbps, large files transfer in seconds. Whether you’re moving work documents, transferring hundreds of gigs of games, or backing up a year’s worth of photos, you get more done in less time.
- 【Sleek, Lightweight, and Ready to Go】 Weighing just 0.16 kg—lighter than a can of soda—this compact drive features a stylish mirror‑and‑frosted finish. Toss it in your bag and go, whether you’re heading to the office, visiting a friend for a gaming session, or giving a presentation on the road.
How heading anchors are formed
- Spaces become hyphens:
## Local Development Setupbecomes#local-development-setup. - Capital letters become lowercase:
## API Referencebecomes#api-reference. - Most punctuation is removed:
## What's New?commonly becomes#whats-new. - Duplicate headings get a number: if there are two headings named
## Usage, the second one may become#usage-1.
For example, a heading such as ## Install & Run may be linked on GitHub as [Install and run](#install--run), because the ampersand is removed and the surrounding spaces become hyphens. Since punctuation handling can vary slightly between platforms, it is best to keep headings simple when you plan to link to them. Clear headings like Installation, Configuration, and Deployment create predictable anchor links.
Linking to nested sections
You can link to any heading level, not only ## headings. Links work with #, ##, ###, and deeper heading levels as long as the renderer creates an anchor for them. For example, if your README contains ### Running Tests, you can link to it with [Running Tests](#running-tests). This is helpful when a larger section contains several smaller steps.
Good internal links should be short, descriptive, and easy to scan. Instead of writing [click here](#configuration), use link text such as [Configuration options](#configuration). If you rename a heading, remember to update any links that point to it. Broken internal links can confuse readers, especially in setup instructions where people may be jumping between prerequisites, commands, and troubleshooting details.
Adding Image Links and Badges
Images in a README.md file use Markdown syntax that looks similar to a regular link, but with an exclamation mark at the beginning. The basic format is . The alt text describes the image for screen readers and is also useful if the image fails to load. For example,  displays an image stored in an assets folder in the same repository.
You can also turn an image into a clickable link by wrapping the image syntax inside regular link syntax. The format is [](target-url). This is commonly used for clickable screenshots, logos, and badges. For example, [](https://example.com/demo) displays an image that takes users to the live demo when clicked. On GitHub, relative paths such as ./assets/logo.png or assets/logo.png usually work well for images stored in your repository.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Adding badges to a README
Badges are small image labels that show project status, version, license, build status, test coverage, package downloads, or supported platforms. They are usually added near the top of a README so visitors can quickly understand the state of the project. Badge providers such as Shields.io generate image URLs that can be used directly in Markdown.
- Static badge:
 - Linked badge:
[](LICENSE) - Build badge:
[](https://github.com/user/repo/actions) - Version badge:
For linked badges, the image URL points to the badge graphic, while the outer link points to the relevant page. A license badge might link to the LICENSE file, a build badge might link to the GitHub Actions page, and a package badge might link to npm, PyPI, or another package registry. This makes badges more useful than plain decorative images because readers can click through for details.
Best practices for images and badges
- Use meaningful alt text: Write
![Login page screenshot]instead of![image]so the content is understandable without seeing it. - Prefer relative paths for repository images: Use
assets/screenshot.pngfor files stored in the repo instead of copying long GitHub image URLs. - Keep badge rows readable: Too many badges can make a README look cluttered. Include only badges that help users evaluate or use the project.
- Check image file names carefully: GitHub paths are case-sensitive, so
Logo.pngandlogo.pngmay not refer to the same file. - Avoid oversized screenshots: Compress large images before adding them to the repository to keep pages loading quickly.
If Markdown image sizing is not enough for your platform, GitHub also allows limited HTML in README files. For example, you can use an <img> tag with a width attribute, such as <img src="assets/screenshot.png" alt="Project screenshot" width="600">. Markdown syntax is simpler and more portable, but HTML can be useful when you need more control over image size or alignment.
Common Mistakes and Best Practices
Links in a README.md file are simple to write, but small formatting errors can make them fail or look unprofessional. Since README files are often viewed on GitHub, GitLab, Bitbucket, package registries, and documentation sites, it is worth checking that every hyperlink works in the places where your project is published. A clean README uses descriptive link text, consistent formatting, and paths that continue to work when the repository is cloned, forked, or browsed from different branches.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Common mistakes
- Reversing the Markdown syntax: Write link text in square brackets and the URL in parentheses, like
[Documentation](https://example.com/docs). Writing(Documentation)[https://example.com/docs]will not create a valid link. - Forgetting the protocol: External links should usually include
https://. For example, usehttps://github.com/user/repoinstead ofgithub.com/user/repoto avoid inconsistent rendering across Markdown tools. - Using broken relative paths: If you link to a file in the repository, check the path from the location of the README. For example,
[Contributing](CONTRIBUTING.md)works only ifCONTRIBUTING.mdis in the same directory as the README. - Adding spaces in URLs without encoding them: Spaces can break links. Use
%20in URLs, or rename files and folders with hyphens, such assetup-guide.mdinstead ofsetup guide.md. - Creating anchor links that do not match headings: Heading links are usually lowercase, with spaces replaced by hyphens. A heading like
## Installation Guideis commonly linked as[Installation Guide](#installation-guide). - Using vague link text: Avoid repeated text such as “click here” or “this link.” Descriptive text like
[View the API documentation](https://example.com/api)is easier to scan and more accessible.
Best practices
Prefer clear, meaningful link labels that tell readers what they will open. For example, [Download the latest release](https://github.com/user/repo/releases/latest) is more helpful than [Download](https://github.com/user/repo/releases/latest) when a README contains several links. If the link points to another file in the same repository, use relative links where possible, such as [License](LICENSE) or [Usage Guide](docs/usage.md). Relative links are shorter and usually continue to work when the repository is forked.
Best Value
- High capacity in a small enclosure – The small, lightweight design offers up to 6TB* capacity, making WD Elements portable hard drives the ideal companion for consumers on the go.
- Plug-and-play expandability
- Vast capacities up to 6TB[1] to store your photos, videos, music, important documents and more
- SuperSpeed USB 3.2 Gen 1 (5Gbps)
Keep link formatting consistent throughout the README. If you use reference-style links for repeated destinations, define them in one section near the bottom of the file so they are easy to update. For example, repeated links to documentation, releases, issues, and discussions can be managed as references instead of duplicated inline URLs. For badge links and image links, always include meaningful alt text, such as [](workflow-url), so readers using assistive technologies understand what the image represents.
Before publishing changes, preview the README on the platform where it will be displayed and test the main links. Pay special attention to heading anchors, renamed files, moved documentation folders, and branch-specific URLs that include main or master. A final check helps prevent dead links and keeps your project page trustworthy, readable, and easy to navigate.
Frequently Asked Questions
How do I add a clickable link in a README.md file?
Use Markdown inline link syntax: put the link text in square brackets and the URL in parentheses. For example, [Visit GitHub](https://github.com) will display as a clickable “Visit GitHub” link on GitHub and most Markdown-supported platforms.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Can I link to another file in the same GitHub repository?
Yes, you can use a relative link instead of a full URL. For example, [Installation Guide](docs/install.md) links to a file inside a docs folder, while [License](LICENSE) links to a file in the repository root.
How do I link to a specific heading inside my README?
GitHub automatically creates anchors for headings in Markdown files. Convert the heading to lowercase, replace spaces with hyphens, and remove most punctuation; for example, a heading named ## Getting Started can be linked with [Getting Started](#getting-started).
What is the difference between inline links and reference-style links?
Inline links keep the URL directly next to the link text, such as [Docs](https://example.com/docs). Reference-style links use a label, such as [Docs][docs-link], with the actual URL defined elsewhere, which can make long README files cleaner and easier to edit.
How do I make an image or badge clickable in README.md?
Wrap the image Markdown inside link Markdown. For example, [](target-url) displays a badge image that opens the target URL when clicked, which is commonly used for build status, package versions, and documentation links.
Bottom Line
Adding links in a README.md file is simple once you know the basic Markdown patterns: inline links for quick references, reference-style links for cleaner long documents, image links for visuals, and anchors for jumping between sections. These options help make your README easier to scan, navigate, and use on GitHub or any Markdown-supported platform.
Before publishing, preview your README, test every link, and use clear link text so readers know exactly where they are going. A well-linked README guides users smoothly from installation steps to documentation, examples, issues, and related resources.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
