DEV Community

Cover image for How to Add a Link or Hyperlink in README.md File
Israel Olaleye
Israel Olaleye

Posted on

How to Add a Link or Hyperlink in README.md File

As a software engineer, one of the first things I learned after pushing my code to GitHub was the importance of a well-structured README.md file. Whether you're open-sourcing a library, sharing a project with your team, or just documenting something for future-you, your README is often the first impression people get of your work.

One of the most common elements you'll need to include in a README is a hyperlink—maybe to your live site, an external documentation page, or even another file in your repository. It sounds simple, but if you're new to Markdown, you might not know the exact syntax.

Let me walk you through it.

Basic Markdown Link Syntax

In Markdown, you add a hyperlink using this syntax:

[Link Text](https://example.com)
Enter fullscreen mode Exit fullscreen mode

  • Link Text is the clickable text that will be shown.

  • https://example.com is the URL the user will be taken to when they click the link.

Example:

Check out my portfolio [here](https://yourwebsite.com).
Enter fullscreen mode Exit fullscreen mode

When rendered, that line becomes

Check out my portfolio here.

Linking to Another File in Your Repo
Sometimes you’ll want to link to another file inside your own project repository—maybe a contribution guide, license, or even another markdown file.

Here’s how:

[CONTRIBUTING.md](CONTRIBUTING.md)
Enter fullscreen mode Exit fullscreen mode

This assumes CONTRIBUTING.md is in the same directory as your README.md.

If it's in a subfolder:

[View API Docs](docs/API.md)
Enter fullscreen mode Exit fullscreen mode

Opening in a New Tab? Not with Vanilla Markdown
If you're coming from HTML, you might be tempted to write this:

<a href="https://example.com" target="_blank">Click me</a>
Enter fullscreen mode Exit fullscreen mode

But most Markdown processors — including GitHub's — don’t support target="_blank". Markdown links open in the same tab by default. If you really need the target="_blank" behavior, you’ll have to fall back to raw HTML:

<a href="https://example.com" target="_blank">Click me</a>
Enter fullscreen mode Exit fullscreen mode

This works in GitHub-flavored Markdown, which supports inline HTML.

Bonus: Reference-Style Links

If you're trying to keep things clean and readable—especially for long documents—reference-style links are a great option:

Read the [official docs][docs-link].

...
Enter fullscreen mode Exit fullscreen mode

This separates the content from the links, which is nice for large documentation files.

My Final Thoughts

I can’t count how many times I’ve had to Google “how to add a link in Markdown” when writing README files in my early days. But once you get the hang of it, it becomes second nature. The simplicity of Markdown is actually what makes it so powerful.

Whether you're linking to your deployed site, another file in your repo, or an external tutorial, now you know exactly how to do it—clean, professional, and properly formatted.

Let your README.md file speak for your project. It's more than just a document—it's your first impression to the world.

Top comments (0)