close
Rspress
  • English
    • 中文
    • English

Links

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

Syntax
Rendered result
[File path format - ../../start/getting-started.mdx](../../start/getting-started.mdx)

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

Within the same Rspress project, it is recommended to use only one type of link format to maintain consistent code style.

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
Rendered result
[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)
Tip

When using absolute paths, the root path is the docs directory. If the project uses internationalization or multi-version, the markdown.link.autoPrefix configuration will automatically add prefixes, so you can omit the language directory in links.

For example:

Absolute path - /guide/start/getting-started.mdx

Absolute path with language - /zh/guide/start/getting-started.mdx

Both will point to the same page.

We recommend using relative file paths as they have the following advantages:

  1. IDE support: hint, jump to the corresponding file, auto-update file links when moving files, etc.

  2. Supported by GitHub interface and other Markdown editors.

  3. Compared to URL format, you don't need to consider the impact of the cleanUrls configuration.

URL format

The URL format uses complete URL addresses to reference specific pages.

Here are examples from this website:

Syntax
Rendered result
[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)
Tip

When using absolute paths, the root path is the docs directory. If the project uses internationalization or multi-version, the markdown.link.autoPrefix configuration will automatically add prefixes, so you can omit the language directory in links.

For example:

Absolute path - /guide/start/getting-started

Absolute path with language - /zh/guide/start/getting-started

Both will point to the same page.

The difference between URL format and file path format is that Rspress will automatically add the .html suffix based on the cleanUrls configuration, so you don't need to consider the .html suffix in links - both with and without it will have consistent rendering results.

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

Links to static resources in the documentation site will be kept as is:

Tip

You need to exclude these links from dead link checking.

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

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

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

Syntax
Rendered result
Rspress supports [relative file paths] and [absolute file paths].

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

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

Syntax
Rendered result
[Jump to #File Path Format](#file-path-format)

[Jump to Getting Started#1-Initialize Project](../../start/getting-started.mdx#1-initialize-project)

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 to automatically check for invalid links.

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

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