On this page
Links & Images
Links in Clay work like links between files on GitHub: you link to the Markdown file, relative to the page you are writing. The same links work on GitHub, in your editor and on the site.
#Links to pages
[Installation](../getting-started/installation.md)
[Alerts](alerts.md)
[Code blocks](./code-blocks.md)Clay resolves the path relative to the current page, drops the .md and turns it into a link that keeps the site’s base URL. Links to folders lead to the folder’s page: the configuration section or the configuration section.
Links starting with / start at the root of the docs: [Pages](/writing/pages.md) links to docs/writing/pages.md from anywhere.
#Links to sections
Add the heading’s anchor after #:
Highlighting lines and images on this page.
[Highlighting lines](code-blocks.md#highlighting-lines)
[Images](#images)Anchors are built like GitHub builds them: lowercase, spaces become hyphens, punctuation is dropped. “Links to sections” becomes #links-to-sections. When unsure, copy the # link next to the heading on the page.
#Links to other websites
[Shiki](https://shiki.style)
[Write to us](mailto:docs@example.com)Links to other websites open in a new tab. mailto:, tel: and similar links are left to the browser.
#Images
Put images next to your pages and reference them relative to the page:
The text in brackets describes the image for screen readers and search engines; always write one. Clay copies every file in docs/ into the site, so docs/writing/img/build-steps.png is published next to this page.
docs/writing
- links-and-images.md
imgnever shows in the navigation: no pages inside
- build-steps.png
#Downloads
Link to any other file the same way, and readers can download it:
[Download the checklist (PDF)](files/checklist.pdf)#Checked on every build
clay build checks every link and image in your docs: pages, files and sections. A link that leads nowhere is reported as a warning:
▲ Broken link in writing/pages.md: "setup.md" points to a missing page (/writing/setup)
▲ Broken link in writing/pages.md: "alerts.md#tipps" points to a missing section (#tipps on /writing/alerts)With --strict, warnings fail the build, so broken links never reach your readers. Links to other websites are not checked. See build checks.