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

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

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

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

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

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

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

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

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

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

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

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

export const frontmatter = {
  // Объявляем тип макета
  // Указанный здесь кастомный макет не будет содержать боковую панель
  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
  }
}