> For AI agents: the complete documentation index is available at https://rspress.rs/llms.txt, the full documentation bundle is available at https://rspress.rs/llms-full.txt.

# Links

## Link format

Rspress supports two formats of links: **file path format** and **URL format**. They render exactly the same results, differing only in code style.


**Syntax**

```mdx
[File path format - ../start/getting-started.mdx](../start/getting-started.mdx)

[URL format - /guide/start/getting-started](/guide/start/getting-started)
```


**Rendered result**

[File path format - ../start/getting-started.mdx](https://rspress.rs/guide/start/getting-started.md)
[URL format - /guide/start/getting-started](https://rspress.rs/guide/start/getting-started.md)


:::tip
Within the same Rspress project, use one link format consistently to keep the code style predictable.
:::

## File path format

The file path format uses **absolute file paths** or **relative file paths** to reference specific `.md` or `.mdx` files.

Here are examples from this website:


**Syntax**

```mdx
[Relative path - ../start/getting-started.mdx](../start/getting-started.mdx)

[Absolute path - /guide/start/getting-started.mdx](/guide/start/getting-started.mdx)

[Absolute path with language - /zh/guide/start/getting-started.mdx](/zh/guide/start/getting-started.mdx)

[Absolute path to another language page - /en/guide/start/getting-started.mdx](/en/guide/start/getting-started.mdx)
```


**Rendered result**

[Relative path - ../start/getting-started.mdx](https://rspress.rs/guide/start/getting-started.md)
[Absolute path - /guide/start/getting-started.mdx](https://rspress.rs/guide/start/getting-started.md)
[Absolute path with language - /zh/guide/start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)
[Absolute path to another language page - /en/guide/start/getting-started.mdx](https://rspress.rs/guide/start/getting-started.md)


:::tip

When using absolute paths, the root path is the [`docs`](https://rspress.rs/api/config/config-basic.md#root) directory. If the project uses [internationalization](https://rspress.rs/guide/basic/i18n.md) or [multi-version](https://rspress.rs/guide/basic/multi-version.md), the [`markdown.link.autoPrefix`](https://rspress.rs/api/config/config-build.md#markdownlinkautoprefix) configuration will automatically add prefixes, so you can omit the language directory in links.

For example:

[Absolute path - /guide/start/getting-started.mdx](https://rspress.rs/guide/start/getting-started.md)

[Absolute path with language - /zh/guide/start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)

Both will point to the same page.

:::

We recommend using relative file paths because they provide the following advantages:

1. IDE support: suggestions, jumping to the corresponding file, automatic link updates when files move, and more.

2. Support in the GitHub UI and other Markdown editors.

3. Unlike URL format, file path links are not affected by the [`cleanUrls`](https://rspress.rs/api/config/config-basic.md#routecleanurls) configuration.

## URL format

The URL format uses route URLs to reference specific pages.

Here are examples from this website:


**Syntax**

```mdx
[Relative path - ../start/getting-started](../start/getting-started)

[Absolute path - /guide/start/getting-started](/guide/start/getting-started)

[Absolute path - /guide/start/getting-started.html](/guide/start/getting-started.html)

[Absolute path with language - /zh/guide/start/getting-started.html](/zh/guide/start/getting-started.html)

[Absolute path to another language page - /en/guide/start/getting-started.html](/en/guide/start/getting-started.html)
```


**Rendered result**

[Relative path - ../start/getting-started](https://rspress.rs/guide/start/getting-started.md)
[Relative path - ../start/getting-started.html](https://rspress.rs/guide/start/getting-started.md)
[Absolute path - /guide/start/getting-started](https://rspress.rs/guide/start/getting-started.md)
[Absolute path - /guide/start/getting-started.html](https://rspress.rs/guide/start/getting-started.md)
[Absolute path with language - /zh/guide/start/getting-started.html](https://rspress.rs/zh/guide/start/getting-started.md)
[Absolute path to another language page - /en/guide/start/getting-started.html](https://rspress.rs/guide/start/getting-started.md)


:::tip

When using absolute paths, the root path is the [`docs`](https://rspress.rs/api/config/config-basic.md#root) directory. If the project uses [internationalization](https://rspress.rs/guide/basic/i18n.md) or [multi-version](https://rspress.rs/guide/basic/multi-version.md), the [`markdown.link.autoPrefix`](https://rspress.rs/api/config/config-build.md#markdownlinkautoprefix) configuration will automatically add prefixes, so you can omit the language directory in links.

For example:

[Absolute path - /guide/start/getting-started](https://rspress.rs/guide/start/getting-started.md)

[Absolute path with language - /zh/guide/start/getting-started](https://rspress.rs/zh/guide/start/getting-started.md)

Both will point to the same page.

:::

The difference between URL format and file path format is that Rspress automatically adds the `.html` suffix according to the [`cleanUrls`](https://rspress.rs/api/config/config-basic.md#routecleanurls) configuration. You do not need to manage the suffix manually; links with or without `.html` render consistently.

## External links

External links that are not in this docsite will automatically add `target="_blank" rel="noreferrer"`:

- [Rspack Documentation](https://rspack.rs/)
- [Rsbuild Documentation](https://rsbuild.rs/)

## Assets links

Links to static resources in the documentation site are preserved as written:

- Static assets in public folder - [/og-image.png](/og-image.png)
- Generated by @rspress/plugin-llms - [/llms-full.txt](/llms-full.txt)

:::tip

You need to exclude these links from [dead link checking](#dead-links-checking).

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: {
        excludes: ['/og-image.png', '/llms-full.txt'],
      },
    },
  },
});
```

:::

## Link definition syntax

Rspress also supports markdown's alternative `definition` syntax for links, which can simplify link writing when there are many links.


**Syntax**

```mdx
Rspress supports [relative file paths] and [absolute file paths].

[relative file paths]: ../start/getting-started.mdx
[absolute file paths]: /guide/start/getting-started.mdx
```


**Rendered result**

Rspress supports [relative file paths] and [absolute file paths].
[relative file paths]: https://rspress.rs/guide/start/getting-started.md
[absolute file paths]: https://rspress.rs/guide/start/getting-started.md


## Anchor links

Rspress supports adding anchor navigation in links, using the `#` symbol to specify jumping to a specific position on the page.


**Syntax**

```mdx
[Jump to #File Path Format](#file-path-format)

[Jump to Getting Started#Create a Rspress project](../start/getting-started.mdx#create-a-rspress-project)
```


**Rendered result**

[Jump to #file-path-format](#file-path-format)
[Jump to Getting Started#Create a Rspress project](https://rspress.rs/guide/start/getting-started.md#create-a-rspress-project)


### Customizing anchor id

By default, Rspress will automatically generate ids based on the content of each title. This id will also serve as the content of the anchor. You can use the following syntax to customize the id of the header:

```md
## Hello world \{#custom-id}
```

Where `custom-id` is your custom id.

## Dead links checking

During the maintenance of documentation sites, broken links often occur. Rspress provides a dead link checking feature to specifically address this troublesome maintenance issue.

Configure through [markdown.link.checkDeadLinks](https://rspress.rs/api/config/config-build.md#markdownlinkcheckdeadlinks) to automatically check for invalid links.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkDeadLinks: true,
    },
  },
});
```

## Dead anchors checking

Rspress can also check whether internal link anchors exist in the target page. It checks same-page anchors, relative links, and absolute links, but skips external URL anchors.

:::info
Anchor checking is currently disabled by default. It will be enabled by default in a future version.
:::

Configure through [markdown.link.checkAnchors](https://rspress.rs/api/config/config-build.md#markdownlinkcheckanchors) to automatically check for invalid anchors.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    link: {
      checkAnchors: true,
    },
  },
});
```

## Dead images checking

Similar to dead link checking, Rspress can also check for broken image references in your documentation. This catches images that reference non-existent local files, including both relative paths and absolute paths that reference the `public` directory.

Configure through [markdown.image.checkDeadImages](https://rspress.rs/api/config/config-build.md#markdownimagecheckdeadimages) to automatically check for invalid images.

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';

export default defineConfig({
  markdown: {
    image: {
      checkDeadImages: true,
    },
  },
});
```