#Ссылки

#Формат ссылок

Rspress поддерживает два формата ссылок: формат пути к файлу и формат URL. По результату рендеринга они полностью идентичны, различаются только стилем написания.

[Формат пути к файлу — ../start/getting-started.mdx](../start/getting-started.mdx)

[Формат URL — /guide/start/getting-started](/guide/start/getting-started)

#Формат пути к файлу

Формат пути к файлу использует абсолютные или относительные пути к конкретным файлам .md или .mdx.

Примеры с этого сайта:

[Относительный путь — ../start/getting-started.mdx](../start/getting-started.mdx)

[Абсолютный путь — /guide/start/getting-started.mdx](/guide/start/getting-started.mdx)

[Абсолютный путь с указанием языка — /ru/guide/start/getting-started.mdx](/ru/guide/start/getting-started.mdx)

[Абсолютный путь на страницу другого языка — /en/guide/start/getting-started.mdx](/en/guide/start/getting-started.mdx)

[Абсолютный путь — /guide/start/getting-started.mdx](/guide/start/getting-started.mdx)

[Абсолютный путь с языком — /ru/guide/start/getting-started.mdx](/ru/guide/start/getting-started.mdx)

Мы рекомендуем использовать относительные пути к файлам, поскольку они предоставляют следующие преимущества:

1. Поддержка 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)

[Абсолютный путь с языком — /ru/guide/start/getting-started.html](/ru/guide/start/getting-started.html)

[Абсолютный путь на страницу другого языка — /en/guide/start/getting-started.html](/en/guide/start/getting-started.html)

[Абсолютный путь — /guide/start/getting-started](/guide/start/getting-started)

[Абсолютный путь с языком — /ru/guide/start/getting-started](/ru/guide/start/getting-started)

Разница между URL-форматом и форматом пути к файлу заключается в том, что Rspress автоматически добавляет суффикс .html в соответствии с конфигурацией cleanUrls. Вам не нужно вручную управлять суффиксом; ссылки с .html или без него отображаются одинаково.

#Внешние ссылки

Внешние ссылки, которые находятся за пределами текущего сайта документации, автоматически получают атрибуты target="_blank" rel="noreferrer":

• Документация Rspack
• Документация Rsbuild

#Ссылки на статические ресурсы

Ссылки на статические ресурсы внутри сайта документации остаются без изменений:

- Статический ресурс из папки public — [/og-image.png](/og-image.png)

- Сгенерированный плагином @rspress/plugin-llms — [/llms-full.txt](/llms-full.txt)

import { defineConfig } from '@rspress/core';

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

#Синтаксис определения ссылок

Rspress также поддерживает альтернативный синтаксис Markdown для «определения ссылок» (definition), который упрощает написание ссылок, когда их много.

Rspress поддерживает [относительные пути к файлам] и [абсолютные пути к файлам].

[относительные пути к файлам]: ../start/getting-started.mdx
[абсолютные пути к файлам]: /guide/start/getting-started.mdx

#Якорные ссылки

Rspress поддерживает якорную навигацию в ссылках — с помощью символа # можно указать переход к определённому месту на странице.

[Перейти к разделу «Формат пути к файлу»](#file-path-format)

[Перейти к разделу «Онлайн-демонстрация» в главе «Быстрый старт»](../start/getting-started.mdx#online-example)

#Настройка собственного идентификатора якоря

По умолчанию Rspress автоматически генерирует идентификатор на основе текста заголовка. Этот идентификатор одновременно используется как якорь. Вы можете задать собственный идентификатор заголовка с помощью следующего синтаксиса:

## Привет, мир \{#custom-id}

Где custom-id — ваш собственный идентификатор.

#Проверка битых ссылок

При поддержке сайтов документации часто появляются битые ссылки. Rspress предоставляет функцию проверки битых ссылок, чтобы решить эту неприятную проблему обслуживания.

Настройте проверку через параметр markdown.link.checkDeadLinks — неработающие ссылки будут обнаруживаться автоматически.

import { defineConfig } from '@rspress/core';

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

#Проверка недействительных якорей

Rspress также может проверять, существуют ли якоря внутренних ссылок на целевой странице. Проверяются якоря на текущей странице, относительные и абсолютные ссылки, но якоря внешних URL пропускаются.

Для автоматической проверки недействительных якорей используйте параметр markdown.link.checkAnchors.

import { defineConfig } from '@rspress/core';

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

#Проверка битых изображений

Аналогично проверке битых ссылок, Rspress также может проверять ссылки на изображения в документации. Это позволяет обнаруживать изображения, которые ссылаются на несуществующие локальные файлы, включая как относительные пути, так и абсолютные пути, ссылающиеся на каталог public.

Настройте проверку с помощью markdown.image.checkDeadImages для автоматической проверки неработающих изображений.

import { defineConfig } from '@rspress/core';

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