Skip to content
logoClay
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.

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.

Add the heading’s anchor after #:

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 next to the heading on the page.

[Shiki](https://shiki.style)
[Write to us](mailto:docs@example.com)

Links to other websites open in a new tab, with a small icon before their text, so readers see they leave the site. 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 Clay logo](../../logo.svg)
![Build steps](img/build-steps.png)

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

Images that the page shows smaller than they are, like most screenshots, open in full when clicked, or with Enter once the keyboard reaches them; a click or Esc closes them. Try it:

A page of these docs in a wide window

The text in brackets shows below the enlarged image. Images in links and cards stay links.

#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.

Type to search all pages.