#Файловая маршрутизация

#Что это такое?

Rspress использует маршрутизацию на основе файловой системы: путь к файлу страницы напрямую преобразуется в путь маршрута. Благодаря этому маршрутизация всего проекта становится интуитивно понятной.

Например, если в директории docs есть файл foo.md, то маршрут к этой странице будет /foo.

#Правила сопоставления

Rspress автоматически сканирует корневую директорию и все вложенные поддиректории, преобразуя пути к файлам в пути маршрутов. Например, при следующей структуре файлов:

docs
├── foo
│   ├── bar.md
│   └── index.md
├── zoo.md
└── index.md

Тогда файл bar.md будет доступен по маршруту /foo/bar, а /foo/index.md — по /foo.

Конкретные правила сопоставления выглядят так:

docs
├── foo
│   └── index.md
└── foo.md

#Маршрутизация через TSX

В рамках маршрутизации по соглашению (помимо файлов .md и .mdx) вы также можете использовать файлы .tsx в качестве компонентов маршрутов. По умолчанию из такого файла экспортируется React-компонент, и этот компонент автоматически регистрируется как страница маршрута. Например:

export default () => {
  return <div>foo</div>;
};

Конечно, если вам нужно настроить собственный макет (layout), вы можете добавить отдельный экспорт, чтобы объявить тип разметки страницы:

export const frontmatter = {
  // Объявляем тип макета
  // Указанный здесь кастомный layout не будет содержать боковую панель
  pageType: 'custom',
};

Подробное описание всех возможных значений pageType смотрите в документации API.

#Пользовательская маршрутизация

Если требуется изменить стандартное поведение маршрутизации, можно воспользоваться полем route в конфигурации:

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

export default defineConfig({
  route: {
    // Эти файлы будут зарегистрированы как маршруты (поддерживаются glob-шаблоны)
    include: ['other-dir/**/*'],
    // Эти файлы не будут зарегистрированы как маршруты (поддерживаются glob-шаблоны)
    exclude: ['component/**/*', 'fragments/**/*'],
  },
});

#Лучшие практики

Рекомендуем размещать файлы документации в директории docs, чтобы сделать проект более понятным. Для контента, не являющегося документацией, такого как пользовательские компоненты, утилитарные функции и т. д., их можно хранить вне директории docs. Если размещать их в директории docs, необходимо использовать route.exclude.

Вот рекомендуемая структура файлов, которая включает фрагменты MDX и компоненты React, пользовательские темы, файловую маршрутизацию и интернационализацию:

├── docs
│   ├── components  # React-компоненты документации
│   │   └── Example.tsx
│   ├── ru
│   │   ├── fragments   # русскоязычные фрагменты
│   │   │   └── example.mdx
│   │   └── index.mdx
│   └── en
│       ├── fragments   # англоязычные фрагменты
│       │   └── example.mdx
│       └── index.mdx
└── theme
    ├── components # React-компоненты темы
    │   └── DocFooter.tsx
    └── index.tsx

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

export default defineConfig({
  route: {
    exclude: ['*/components/**/*', '*/fragments/**/*'], // Файлы в этих директориях не будут зарегистрированы как маршруты
  },
  lang: 'en',
  locales: [
    {
      lang: 'ru',
      label: 'Русский',
    },
    {
      lang: 'en',
      label: 'English',
    },
  ],
});

{
  "compilerOptions": {
    "lib": ["DOM", "ESNext"],
    "jsx": "react-jsx",
    "moduleResolution": "bundler",
    "paths": {
      "i18n": ["./i18n.json"],
      "@theme": ["./theme/index.tsx"]
    }
  },
  "include": ["docs", "theme", "rspress.config.ts"],
  "mdx": {
    "checkMdx": true
  }
}