The simplest way to link text in GitHub

To add a hyperlink over text in GitHub, wrap the text in square brackets and put the URL in parentheses directly after, with no space between them. The format is [your text here](https://example.com). GitHub reads this as Markdown — a plain-text formatting language — and converts it to a clickable link when you save or preview your file.

This works in README files, issues, pull requests, comments, and any other place GitHub accepts Markdown. The link appears blue and underlined in the final view, and readers can click it to visit the URL you specified.

Key Takeaways

  • The Markdown syntax for a hyperlink is square brackets around the text, followed when ready by parentheses around the URL: [text](url).
  • You can use this format in README files, commit messages, issues, pull requests, and comments anywhere on GitHub.
  • The preview tab shows you how the link will look before you save or post it.
  • If your URL contains special characters, wrap it in angle brackets: [text](<https://example.com/path?query=value>).

Where you can add hyperlinks in GitHub

GitHub accepts Markdown hyperlinks in most text fields. The most common places are README.md files (the main description file in a repository), pull request descriptions, issue descriptions, and comments on issues or pull requests. You can also use them in wiki pages if your repository has one enabled.

Commit messages do not support Markdown formatting, so hyperlinks will not work there. If you need to reference a URL in a commit message, paste the full URL as plain text instead.

How to write the hyperlink syntax correctly

The order matters: text first, URL second. Write the text you want readers to see inside square brackets, then when ready follow with the URL inside parentheses. For example, [Visit the Python website](https://www.python.org) creates a link where "Visit the Python website" is the clickable text.

Do not add a space or line break between the closing bracket and the opening parenthesis. [text] (url) with a space will not work. The parentheses must touch the bracket directly.

If your URL contains spaces or special characters like question marks or ampersands, wrap the entire URL in angle brackets: [search results](<https://example.com/search?q=github+markdown>). This tells GitHub to treat everything inside the angle brackets as part of the URL.

Using the preview tab before you save

GitHub shows you two tabs when you edit a file or write a comment: "Write" and "Preview". The Write tab is where you type your Markdown. Click the Preview tab to see how your hyperlink will look after you save it — the text will appear blue and underlined, and you can verify the link goes to the right place.

If the link does not appear blue in the preview, check that your square brackets and parentheses are in the right order with no space between them. Fixing the syntax in the Write tab and switching back to Preview will show the corrected version when ready.

Linking to other files and sections within your repository

You can link to other files in the same repository by using a relative path instead of a full URL. For example, [See the contributing guide](./CONTRIBUTING.md) links to a file called CONTRIBUTING.md in the same folder. Use ../ to go up one folder level: [Parent folder file](../other-folder/file.md).

To link to a specific section within a file, add a hash and the section heading in lowercase with hyphens instead of spaces. For example, [Jump to installation](./README.md#installation-instructions) links to a heading called "Installation Instructions" in the README file. GitHub automatically creates these anchor links from your headings, so you do not need to set them up separately.

Common mistakes and how to fix them

The most frequent error is putting a space between the closing bracket and opening parenthesis: [text] (url). GitHub will not recognize this as a link. Remove the space and it will work.

Another common issue is forgetting the https:// at the start of the URL. [text](example.com) may not work as expected; always include the full protocol. If you are linking to a file within your repository, you do not need https — just use the relative path like ./filename.md.

If your URL contains parentheses (like some Wikipedia links do), wrap the entire URL in angle brackets: [article](<https://en.wikipedia.org/wiki/Example_(disambiguation)>). Without the angle brackets, GitHub may misread where the URL ends.

Frequently Asked Questions

Can I make a hyperlink in a commit message?

No, commit messages do not support Markdown formatting. Paste the full URL as plain text instead, and GitHub will automatically detect it and make it clickable in the commit view.

What if I want the link to open in a new tab?

Standard Markdown hyperlinks do not have a built-in way to open in a new tab. Readers can right-click the link and choose "Open in new tab" themselves. If you need this behavior, you would have to use HTML instead of Markdown, but most GitHub contexts do not allow raw HTML for security reasons.

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

Yes. Click the line number in the file view on GitHub, and the URL in your browser will update to include that line. Copy that URL and use it in your Markdown link. For example, [See line 42](https://github.com/user/repo/blob/main/file.py#L42) links directly to line 42.

Do I need to test the link after I save it?

It is a good idea to click the link once after you save to confirm it goes where you intended. If the link is broken, edit the file or comment again, fix the URL, and save. GitHub will update it when ready.