🚧 Rspress 2.0 文档还在开发中
close
Rspress
  • 中文

      • 链接

      链接形式

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

      语法
      渲染结果
      [文件路径形式 - ../start/getting-started.mdx](../start/getting-started.mdx)

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

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

      文件路径形式

      文件路径形式的特点是使用 绝对文件路径 或者 相对文件路径 来引用到具体的 .md 或 .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)
      Tip

      当使用绝对路径时，根路径为 docs 目录。如果项目中使用了 国际化 或 多版本，markdown.link.autoPrefix 配置项会自动添加前缀，所以在链接中可以省略语言目录。

      比如：

      绝对路径 - /guide/start/getting-started.mdx

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

      均会指向同一页面。

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

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

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

      3. 相比 URL 形式，无需考虑 cleanUrls 配置项。

      URL 形式

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

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

      语法
      渲染结果
      [相对路径 - ../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)
      Tip

      当使用绝对路径时，根路径为 docs 目录。如果项目中使用了 国际化 或 多版本，markdown.link.autoPrefix 配置项会自动添加前缀，所以在链接中可以省略语言目录。

      比如：

      绝对路径 - /guide/start/getting-started

      包含语言的绝对路径 - /zh/guide/start/getting-started

      均会指向同一页面。

      URL 形式与文件路径形不同的一点是，Rspress 会根据 cleanUrls 配置项自动添加 .html 后缀，所以在链接中无需考虑 .html 后缀，含有或不含有都将有一致的渲染结果。

      外部链接

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

      静态资源链接

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

      Tip

      需要在 死链检查 排除该链接。

      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 语法，当链接较多时可以用该语法来简化链接书写。

      语法
      渲染结果
      Rspress 支持 [相对文件路径] 和 [绝对文件路径]。

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

      锚点链接

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

      语法
      渲染结果
      [跳转到 #文件路径形式](#文件路径形式)

[跳转到 快速开始#1-初始化项目](../start/getting-started.mdx#1-初始化项目)

      自定义锚点 id

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

      ## Hello world \{#custom-id}

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

      死链检查

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

      通过 markdown.link.checkDeadLinks 配置进行配置，自动对失效的链接进行检查。

      rspress.config.ts
      import { defineConfig } from '@rspress/core';

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