Links

Write local links relative to the source file. PureStack resolves them to public URLs and fails the build when the target page or asset is missing. Root-relative public URLs, external destinations, and fragment IDs have different validation rules, described below.

Link to another page

Start from the file you are writing in, just like in your editor's file tree. Take this content folder:

index.mdx
guides/
  index.mdx
  semantic-tones.mdx
  themes.mdx
  components/
    index.mdx
    buttons.mdx

From guides/semantic-tones.mdx, these links work:

The file extension is optional. ./themes and ./themes.mdx open the same page.

A folder's main page is its index.mdx, or a file named after the folder, such as components/components.mdx. Link to the folder, like ./components/, and you reach it either way.

Jump to a section

Add # and the section name after the page:

[Create a skin](./themes#create-a-skin)
[Back to the top](#links)

A section name is its heading in lowercase, with hyphens between the words. The heading "Create a skin" becomes #create-a-skin. Try it: create a skin.

PureStack checks that the page exists, not the section, so double-check section names after you rename a heading.

Links in components

The same rule works for href on any tag, including components and links they build from a value:

<BtnLink href="./themes" tone="accent">Read about themes</BtnLink>

<BtnLink :href="nextPage">Next</BtnLink>

<a href="../">Back to home</a>

Links in a shared header or footer start from that header or footer file, so they work on every page that shows them.

Images and files

Images, videos, downloads, and other files in your content folder follow the same rule:

![Palette diagram](./images/palette.svg)

[Download the checklist](./checklist.pdf)

<img src="./images/logo.png" srcset="./images/logo.png 1x, ./images/logo@2x.png 2x" alt="PureStack">

<video src="./intro.mp4" poster="./intro.jpg" controls></video>

Write a file's full name, with its extension and the same capitals, so it works on any host.

Files that a build step writes straight into the output aren't in your content folder, so PureStack can't check them. Link them from the site root, such as /previews/demo.html.

Link outside your content

Anything that starts with / or a protocol is used as written:

PureStack doesn't check these links, because the pages behind them aren't part of your content folder.

You can link your own pages this way too, as in /guides/styling/themes/, but a relative link is the better habit: if that page moves, the build tells you.

If the site lives under a base path, such as /docs, PureStack adds it to every link for you. Set it once in the site configuration.

When a link is broken

The build stops and names the file and the link:

Content link "./themse" in "guides/semantic-tones.mdx" does not match any page or file.

While purestack serve runs, only that page shows the error, and it updates as soon as you fix the link. Most fixes are one of these:

• A typo or different capitals. ./Themes doesn't find themes.mdx, and ./Logo.png doesn't find logo.png.
• The page or file moved. Write the path again, starting from your file.
• The page is built elsewhere. Start the path at the site root, such as /blog/.

Translated sites

Link pages inside your language folder as usual. If a page isn't translated yet, the link opens the default language's version, so you can translate at your own pace.

Quick reference