Links and images share one syntax, and a small change in how you write it determines whether it keeps working when the file moves. This guide covers the forms you will meet in the wild and when to use each.
Inline links
The standard form puts the text in square brackets and the address in parentheses, with no space between them:
[Docento](https://docento.app)
You can add a title, which most renderers show as a tooltip:
[Docento](https://docento.app "PDF tools in your browser")
If the address contains spaces, encode them as %20 or wrap the address in angle brackets where your renderer supports it.
Reference links
For a document with many links, or the same link repeated, you can separate the text from the address:
Read the [guide][1] or the [FAQ][faq].
[1]: https://example.com/guide
[faq]: https://example.com/faq "Frequently asked questions"
The definitions can sit anywhere in the file, and are not shown in the output. Reference links keep paragraphs readable in the source and let you change a URL once for several mentions. Labels are matched case-insensitively.
Automatic links
Angle brackets turn a URL or email address into a link without separate text: <https://example.com>. GitHub Flavored Markdown also links bare URLs automatically, but plain CommonMark does not, so wrap URLs in angle brackets if portability matters.
Relative links
Inside a project, link to other files with a path relative to the current file:
See the [setup instructions](docs/setup.md).
Relative links survive when the repository is cloned or forked, whereas absolute links to a particular site break when the project moves. They resolve against whatever base the viewer is using, so check how your platform treats them. Anchors work for headings in many renderers, for example [Jump](#installation), but the way a heading is turned into an anchor differs between tools.
Images
An image is a link preceded by an exclamation mark, with the description in the brackets:
The text in brackets is alt text. It appears when the image does not load and is read by screen readers, so describe what the image shows, not its file name. If an image is purely decorative, use empty brackets, , so assistive technology skips it.
To make an image a link, nest it: [](https://example.com).
Size and alignment
CommonMark has no syntax for image size or alignment. Some renderers add their own, and many allow raw HTML such as <img src="..." width="300">. Raw HTML may be stripped on some platforms, so test where the file will be used.
Local images and portability
An image path that works on your machine may not on someone else's. Keep images next to the document or in a folder inside the project and use relative paths. When you convert a Markdown file to another format, a missing image is a common failure; see how to convert Markdown to PDF.
Common mistakes
- A space between
]and(turns the link into plain text. - Missing
!makes an image appear as a link. - Unencoded spaces in file names end the URL early.
- Mismatched reference labels, such as
[guide][1]with[one]: ..., leave the text unlinked. - Links with the text and URL reversed.
Check your links
Preview the file and click through. In Docento's Text & Markdown Editor, the rendered view shows each link so you can click through and verify it; the toolbar's Link button inserts [text](url) and selects the placeholder so you can type over it.
Takeaway
Use inline links for one-offs, reference links for repeated or numerous links, relative paths inside a project and meaningful alt text on every image. Preview and click each link before you publish.
