# Links and images

Link to other pages with relative Markdown paths and add images from the project folder.

## Links to other pages

Link to another page with a relative path to its Markdown file. docsp rewrites it to the page URL in the same locale
and version, so the same link works in every translation and every version folder.

```md
Read [the quickstart](./quickstart.md) first.
See [rate limits](../api/errors.md#rate-limits).
```

- A link to `index.md` points to the section page.
- A `#fragment` is kept. Heading ids are the heading text in lower case, with spaces as `-` and punctuation removed;
  a repeated heading gets `-2`, `-3`.
- Links that start with `/`, `#` or a scheme such as `https:` are left as they are.
- Links inside table cells are not rewritten. Use absolute page URLs there.

:::warning[Links are not checked.]
docsp does not check that the target of a relative link exists. A link to a missing file becomes a URL that returns
404. Check links in your CI; see [CI checks](../features/ci-checks.md).
:::

## Images

Put images in the project folder, for example in `docs/assets/`, and reference them with a path relative to the
Markdown file. docsp serves them under `/_assets/<project>/`.

```md
![The send screen](../../assets/sends-light.svg)
```

For an image with a dark mode variant and a caption, use [`::figure`](./directives.md#figure).

## Raw HTML

HTML in Markdown is dropped, including placeholders written as `<name>` in running text. Put placeholders in code
spans: `` `<project>` ``.
