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

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

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

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

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

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

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

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

Далее `bar.md` будет доступен по маршруту `/foo/bar`, а `/foo/index.md` — по маршруту `/foo/`.

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

| Путь к файлу    | Путь маршрута | Путь `cleanUrl: false` |
| --------------- | ------------- | ---------------------- |
| `index.md`      | `/`           | `/index.html`          |
| `/zoo.md`       | `/zoo`        | `/zoo.html`            |
| `/foo/index.md` | `/foo/`       | `/foo/index.html`      |
| `/foo/bar.md`   | `/foo/bar`    | `/foo/bar.html`        |

:::warning Предупреждение

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

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

:::

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

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

```tsx title="foo.tsx"
export default () => {
  return <div>foo</div>;
};
```

Чтобы настроить макет, экспортируйте `frontmatter` и укажите тип макета:

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

Подробное описание всех возможных значений `pageType` смотрите в [документации API](/rspress-russian/api/config/config-frontmatter.md#pagetype).

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

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

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

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

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

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

:::tip

Если вы размещаете пользовательские компоненты или фрагменты документов в директории `docs`, используйте `route.exclude`; в противном случае эти файлы автоматически регистрируются как маршруты и могут привести к неожиданному поведению.

:::

Вот рекомендуемая структура файлов, которая включает [фрагменты MDX и компоненты React](/rspress-russian/guide/use-mdx/components.md#fragments), [пользовательские темы](/rspress-russian/guide/basic/custom-theme.md), [файловую маршрутизацию](/rspress-russian/guide/basic/conventional-route.md) и [интернационализацию](/rspress-russian/guide/basic/i18n.md):

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

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

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

```json title="tsconfig.json"
{
  "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
  }
}
```
