Markdown links
A link is the text in square brackets followed immediately by the URL in round brackets. No space between the two, which is the mistake that catches everyone once.
See the viewer and the compatibility table.
The definitions can sit anywhere in the file, usually at the bottom, and they do not render.
What usually goes wrong
- No space between
]and(. With a space it renders as literal brackets followed by text in parentheses. - A URL with spaces or brackets in it needs angle brackets around it:
[text](<https://example.com/a file>), or percent-encode the spaces. - An anchor link points at a heading's generated id: lowercase, punctuation dropped, spaces to dashes.
## My Section!becomes#my-section. - A bare URL is not always a link. GitHub turns it into one, strict markdown does not.
<https://example.com>works everywhere.
Where it behaves differently
It renders as written on GitHub, GitLab, VS Code preview, Notion and Discord. Everywhere else in this table it does something else, and that is worth reading before you paste.
| Platform | Behaviour |
|---|---|
| Obsidian | Also [[Note name]] for a link to another note, which is Obsidian's own. |
| Slack | Angle brackets and a pipe: <https://example.com|text>. |
For the .md file that arrives in Mail
A markdown file on a phone is the worst case: no editor, no preview, and a share sheet full of apps that want to import it into a library. The iPhone and iPad app opens it where it landed, renders it, and lets you edit and save it back.
Soon on theApp StoreDigital Sandbox, who are building it →
For iPhone and iPad.