Adding a hyperlink in GitHub uses Markdown syntax, not HTML

GitHub reads Markdown, not HTML code. To add a clickable link over text in any GitHub file, README, or comment, you wrap the text in square brackets and put the URL in parentheses immediately after, with no space between them. The format is [your text here](https://example.com).

This works in README files, issue descriptions, pull request comments, discussions, and any other place on GitHub that accepts Markdown. The link will render as blue, underlined text that readers can click.

Key Takeaways

  • The Markdown syntax for a hyperlink is [text](url) with no space between the brackets and parentheses.
  • GitHub automatically converts this format to a clickable link in README files, comments, and pull requests.
  • You can link to external websites, other GitHub repositories, or specific files within your own repository.
  • Preview your changes before saving to make sure the link renders correctly and points to the right place.
  • Common mistakes like adding a space between brackets and parentheses, or forgetting https://, will prevent the link from working.

The basic syntax for any link

Start with your link text inside square brackets: [Click here]. Immediately after, add the URL inside parentheses: (https://example.com). Put them together with no space: [Click here](https://example.com).

When you save or commit the file, GitHub converts this to an actual hyperlink. The text "Click here" becomes blue and underlined, and clicking it takes you to the URL. You can use any text you want between the brackets — it does not have to say "click here".

Linking to files and folders in your own repository

You can link to other files in the same repository without typing the full web address. Use a relative path instead. If you have a file called INSTALL.md in the root of your repository, link to it with [Installation instructions](INSTALL.md).

For files in subfolders, include the folder name: [API documentation](docs/api.md). For files in a parent folder, use ../: [Main readme](../README.md). GitHub automatically converts these to the correct web URL when the file is viewed on the website.

This approach is useful in README files that point readers to other documentation in your repository. The link works whether someone is reading on GitHub's website or in a local clone of the repository.

Linking to specific sections within a file

You can link directly to a heading in another file or the same file. GitHub automatically creates anchor links from every heading. The anchor is the heading text converted to lowercase with hyphens instead of spaces.

If a file has a heading called "Getting Started", the anchor is #getting-started. Link to it with [Jump to setup](INSTALL.md#getting-started). For a heading in the same file, use just the anchor: [See requirements](#requirements).

This is especially helpful in long README files where you want to let readers jump to the section they need without scrolling through everything above it.

Where you can use Markdown links in GitHub

Markdown hyperlinks work in README files, any .md file in your repository, issue descriptions, pull request descriptions, comments on issues and pull requests, and GitHub Discussions. They also work in commit messages, though the link won't be clickable in the commit history itself — only when you view the commit details on the web.

Markdown does not work in file names, branch names, or the title field of issues and pull requests. In those places, GitHub treats the text as plain text and does not convert it to a link. If you need a link in a title, you have to use the full URL instead.

How to check your link before saving

When you are editing a file on GitHub's website, click the "Preview" tab above the text box to see how your Markdown will render. Your hyperlinks will appear as blue text, and you can verify they point to the right place before you commit.

If you are editing locally on your computer, you can use a Markdown preview tool or editor that shows you the rendered output. This catches mistakes like missing parentheses or typos in the URL before you push to GitHub. Many code editors like Visual Studio Code have built-in Markdown preview.

Common mistakes that break hyperlinks

The most common error is putting a space between the closing bracket and the opening parenthesis: [text] (url) instead of [text](url). GitHub will not convert this to a link. Another mistake is forgetting the https:// at the start of external URLs — GitHub may not recognize it as a link without the protocol.

If you are linking to a file in your repository and the file name has spaces or special characters, make sure the path matches exactly. GitHub is case-sensitive on Linux and Mac servers, so [link](README.md) and [link](readme.md) point to different files if your server is case-sensitive. Windows servers are not case-sensitive, but it is still good practice to match the exact case.

Frequently Asked Questions

Can I make a link open in a new tab?

Markdown does not support opening links in a new tab. If you use HTML syntax instead — <a href="url" target="_blank">text</a> — GitHub will render it and the link will open in a new tab. However, most GitHub files accept only Markdown, so HTML may not work everywhere.

What if the URL has parentheses in it?

If the URL itself contains parentheses, escape them with a backslash: [text](https://example.com/page\(1\)). Alternatively, use angle brackets around the URL: [text](<https://example.com/page(1)>).

Can I link to a specific line number in a file?

Yes. When you view a file on GitHub, click the line number to highlight it, then copy the URL from your browser's address bar. That URL includes the line number. You can paste it into a Markdown link: [See line 42](https://github.com/user/repo/blob/main/file.js#L42).

Do I need to include www in the URL?

No. [text](https://example.com) and [text](https://www.example.com) both work. Use whichever form the website actually uses — some sites redirect one to the other, but it is cleaner to match the real address.