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)Installation, Alerts, Code blocks
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 work too, and 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](code-blocks.md#highlighting-lines)
[Images](#images)Highlighting lines and images on this page.
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 from the page’s table of contents.
#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.
Tip
Keep images in an img/ folder next to the pages that use them. Folders without Markdown files never appear in the navigation.
#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. A link to a page that does not exist, or an image that is missing, is reported as a warning:
▲ Broken link in writing/pages.md: "setup.md" points to a missing page (/writing/setup)With --strict, warnings fail the build, so broken links never reach your readers. See build checks.
Note
Links to other websites and #anchors are not checked.