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

# 链接

## 链接形式

Rspress 支持两种形式的链接：**文件路径形式** 和 **URL 形式**。它们的渲染结果完全相同，仅是在代码风格上有所区分。


**语法**

```mdx
[文件路径形式 - ../start/getting-started.mdx](../start/getting-started.mdx)

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


**渲染结果**

[文件路径形式 - ../start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)
[URL 形式 - /guide/start/getting-started](https://rspress.rs/zh/guide/start/getting-started.md)


:::tip
在同一个 Rspress 项目中，推荐只使用一种形式的链接，保持代码风格统一。
:::

### 文件路径形式

文件路径形式的特点是使用 **绝对文件路径** 或者 **相对文件路径** 来引用到具体的 `.md` 或 `.mdx` 文件。

以下是在这个网站中的示例：


**语法**

```mdx
[相对路径 - ../start/getting-started.mdx](../start/getting-started.mdx)

[绝对路径 - /guide/start/getting-started.mdx](/guide/start/getting-started.mdx)

[包含语言的绝对路径 - /zh/guide/start/getting-started.mdx](/zh/guide/start/getting-started.mdx)

[另一语言该页面的绝对路径 - /en/guide/start/getting-started.mdx](/en/guide/start/getting-started.mdx)
```


**渲染结果**

[相对路径 - ../start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)
[绝对路径 - /guide/start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)
[包含语言的绝对路径 - /zh/guide/start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)
[另一语言该页面的绝对路径 - /en/guide/start/getting-started.mdx](https://rspress.rs/guide/start/getting-started.md)


:::tip

当使用绝对路径时，根路径为 [`docs`](https://rspress.rs/zh/api/config/config-basic.md#root) 目录。如果项目中使用了 [国际化](https://rspress.rs/zh/guide/basic/i18n.md) 或 [多版本](https://rspress.rs/zh/guide/basic/multi-version.md)，[`markdown.link.autoPrefix`](https://rspress.rs/zh/api/config/config-build.md#markdownlinkautoprefix) 配置项会自动添加前缀，所以在链接中可以省略语言目录。

比如：

[绝对路径 - /guide/start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)

[包含语言的绝对路径 - /zh/guide/start/getting-started.mdx](https://rspress.rs/zh/guide/start/getting-started.md)

均会指向同一页面。

:::

我们更推荐相对文件路径的形式，它具有以下优点：

1. IDE 支持，提供代码提示、跳转到对应文件、移动文件时自动更新链接等功能。

2. 被 Github 界面或者其他 Markdown 编辑器所支持。

3. 相比 URL 形式，无需考虑 [`cleanUrls`](https://rspress.rs/zh/api/config/config-basic.md#routecleanurls) 配置项。

### URL 形式

URL 形式的特点是使用完整的 URL 地址来引用到具体的页面。

以下是在这个网站中的示例：


**语法**

```mdx
[相对路径 - ../start/getting-started](../start/getting-started)

[绝对路径 - /guide/start/getting-started](/guide/start/getting-started)

[绝对路径 - /guide/start/getting-started.html](/guide/start/getting-started.html)

[包含语言的绝对路径 - /zh/guide/start/getting-started.html](/zh/guide/start/getting-started.html)

[另一语言该页面的绝对路径 - /en/guide/start/getting-started.html](/en/guide/start/getting-started.html)
```


**渲染结果**

[相对路径 - ../start/getting-started](https://rspress.rs/zh/guide/start/getting-started.md)
[相对路径 - ../start/getting-started.html](https://rspress.rs/zh/guide/start/getting-started.md)
[绝对路径 - /guide/start/getting-started](https://rspress.rs/zh/guide/start/getting-started.md)
[绝对路径 - /guide/start/getting-started.html](https://rspress.rs/zh/guide/start/getting-started.md)
[包含语言的绝对路径 - /zh/guide/start/getting-started.html](https://rspress.rs/zh/guide/start/getting-started.md)
[另一语言该页面的绝对路径 - /en/guide/start/getting-started.html](https://rspress.rs/guide/start/getting-started.md)


:::tip

当使用绝对路径时，根路径为 [`docs`](https://rspress.rs/zh/api/config/config-basic.md#root) 目录。如果项目中使用了 [国际化](https://rspress.rs/zh/guide/basic/i18n.md) 或 [多版本](https://rspress.rs/zh/guide/basic/multi-version.md)，[`markdown.link.autoPrefix`](https://rspress.rs/zh/api/config/config-build.md#markdownlinkautoprefix) 配置项会自动添加前缀，所以在链接中可以省略语言目录。

比如：

[绝对路径 - /guide/start/getting-started](https://rspress.rs/zh/guide/start/getting-started.md)

[包含语言的绝对路径 - /zh/guide/start/getting-started](https://rspress.rs/zh/guide/start/getting-started.md)

均会指向同一页面。

:::

URL 形式与文件路径形不同的一点是，Rspress 会根据 [`cleanUrls`](https://rspress.rs/zh/api/config/config-basic.md#routecleanurls) 配置项自动添加 `.html` 后缀，所以在链接中无需考虑 `.html` 后缀，含有或不含有都将有一致的渲染结果。

## 外部链接

非本文档站的外部链接会自动添加 `target="_blank" rel="noreferrer"`:

- [Rspack 文档](https://rspack.rs/)

- [Rsbuild 文档](https://rsbuild.rs/)

## 静态资源链接

文档站中的静态资源链接会原样保留：

- public 文件夹中的静态资源 - [/og-image.png](/og-image.png)
- @rspress/plugin-llms 生成的 - [/llms-full.txt](/llms-full.txt)

:::tip

需要在 [死链检查](#死链检查) 排除该链接。

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

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

:::

## definition 语法链接

Rspress 也支持 markdown 链接的另一 definition 语法，当链接较多时可以用该语法来简化链接书写。


**语法**

```mdx
Rspress 支持 [相对文件路径] 和 [绝对文件路径]。

[相对文件路径]: ../start/getting-started.mdx
[绝对文件路径]: /guide/start/getting-started.mdx
```


**渲染结果**

Rspress 支持 [相对文件路径] 和 [绝对文件路径]。
[相对文件路径]: https://rspress.rs/zh/guide/start/getting-started.md
[绝对文件路径]: https://rspress.rs/zh/guide/start/getting-started.md


## 锚点链接

Rspress 支持在链接中添加锚点跳转，使用 `#` 符号来指定跳转到页面中的特定位置。


**语法**

```mdx
[跳转到 #文件路径形式](#文件路径形式)

[跳转到 快速开始#创建 Rspress 项目](../start/getting-started.mdx#创建-rspress-项目)
```


**渲染结果**

[跳转到 #文件路径形式](#文件路径形式)
[跳转到 快速开始#创建 Rspress 项目](https://rspress.rs/zh/guide/start/getting-started.md#%E5%88%9B%E5%BB%BA-rspress-%E9%A1%B9%E7%9B%AE)


## 自定义锚点 id

默认情况下，Rspress 会根据各个标题的内容自动生成 id，这个 id 也会作为锚点的内容，你可以通过如下的语法来自定义 header 的 id:

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

其中 `custom-id` 就是你自定义的 id。

## 死链检查

在文档站维护过程中，经常出现链接失效的情况。对此 Rspress 提供了死链检查功能，专门处理这一维护中让人头疼的问题。

通过 [markdown.link.checkDeadLinks](https://rspress.rs/zh/api/config/config-build.md#markdownlinkcheckdeadlinks) 配置进行配置，自动对失效的链接进行检查。

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

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

## 失效锚点检查

Rspress 也可以检查站内链接中的锚点是否存在于目标页面中。它会检查当前页面锚点、相对路径链接和绝对路径链接，但会跳过外部 URL 中的锚点。

:::info
锚点检查当前默认关闭，未来版本会默认开启。
:::

通过 [markdown.link.checkAnchors](https://rspress.rs/zh/api/config/config-build.md#markdownlinkcheckanchors) 配置即可自动检查无效锚点。

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

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

## 失效图片检查

类似于死链检查，Rspress 也可以检查文档中的失效图片引用。这能够发现指向不存在本地文件的图片，包括相对路径图片和引用 `public` 目录的绝对路径图片。

通过 [markdown.image.checkDeadImages](https://rspress.rs/zh/api/config/config-build.md#markdownimagecheckdeadimages) 配置即可自动检查无效图片。

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

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