Markdown links look simple: put the visible text in square brackets and the destination in parentheses. Real documents quickly need more than the basic form, however. Links may point to websites, another file, a heading on the same page, or an image stored beside the document. This guide covers the useful forms and the mistakes that make otherwise valid links stop rendering.
The standard syntax is:
[Visible link text](https://example.com)The result is a clickable phrase rather than a visible URL. You can add an optional title, which some browsers show as a tooltip:
[Project documentation](https://example.com/docs "Open the documentation")Use descriptive link text. “Read the deployment guide” tells readers where a link goes; “click here” does not. Descriptive text also makes a page easier to scan with assistive technology.
Documentation repositories commonly use relative paths:
[Installation guide](./guides/installation.md)
[Contributing](../CONTRIBUTING.md)./ starts in the current file's directory. ../ moves up one directory. These links are portable while the repository structure remains intact, but they can break when a single Markdown file is copied into an online viewer without the surrounding files.
Use an absolute HTTPS URL when the destination should work independently of the repository:
[Published installation guide](https://docs.example.com/installation)An anchor link jumps to a section on the rendered page:
[Skip to troubleshooting](#troubleshooting)
## TroubleshootingRenderers normally turn headings into lowercase IDs, replace spaces with hyphens, and remove some punctuation. Exact rules vary. A link such as #api-reference is usually safe for a heading named “API Reference,” but duplicate headings and punctuation-heavy titles deserve testing in the final renderer.
For a heading in another file, combine a path and fragment:
[Authentication errors](./api.md#authentication-errors)A raw space can terminate a Markdown destination. For URLs containing spaces, encode them as %20 or enclose the destination in angle brackets:
[Release notes](<https://example.com/releases/Version 2.md>)Balanced parentheses are accepted by CommonMark, but complicated URLs are easier to maintain when percent-encoded. If a link renders partly as plain text, inspect spaces and parentheses before changing the brackets.
Long destinations can make prose difficult to edit. Reference-style links move URLs out of the sentence:
Read the [API guide][api] and [security policy][security].
[api]: https://example.com/api
[security]: https://example.com/security "Security policy"This is particularly useful when one destination appears several times. Reference labels are matched case-insensitively by CommonMark, but consistent lowercase labels are easier to maintain.
You can also use a compact form when the visible text and reference label match:
Read the [contributing guide].
[contributing guide]: https://example.com/contributingAn image uses the same destination rules with an exclamation mark before the opening bracket:
Text inside the brackets becomes the image description and normally maps to HTML alt text. Describe the information conveyed by the image rather than writing “image” or repeating the filename.
A local image path is valid Markdown:
It will only render when the viewer can also reach that file relative to the Markdown document. Uploading or sharing the .md file alone does not automatically include its image folder.
Angle brackets create explicit autolinks in CommonMark:
<https://example.com>
<team@example.com>Some Markdown flavors automatically link bare URLs, but explicit syntax is more portable. Use a normal descriptive link for polished documentation and an autolink when displaying the destination itself is useful.
When a Markdown link does not work:
Paste the document into mdview.io to inspect the rendered links alongside the rest of the Markdown. Link syntax defines the destination, but the final location determines whether that destination can actually be reached.