Названия файлов

MDX — это расширение Markdown, позволяющее использовать JSX внутри Markdown-документов. Важной особенностью работы с MDX является строгая организация файловой структуры и выбор правильных названий файлов, так как это напрямую влияет на импорт, рендеринг и маршрутизацию.

Расширение файлов

Файлы MDX должны иметь расширение .mdx. Использование других расширений, таких как .md или .js, не позволит корректно обработать MDX-синтаксис и встроенные JSX-компоненты. Пример корректного имени файла:

Article.mdx

При этом, соблюдение регистра символов в именах файлов особенно важно в операционных системах, чувствительных к регистру, таких как Linux и macOS. Например, article.mdx и Article.mdx будут рассматриваться как разные файлы.

Структура имен файлов

MDX-файлы часто используются в связке с генерацией статических сайтов или документацией, поэтому название файла играет роль в формировании URL. Общие рекомендации:

  • Использовать кегель-стиль: слова через дефис, без пробелов и специальных символов, например introduction-to-mdx.mdx.
  • Избегать символов, кроме латинских букв, цифр и дефиса.
  • Для версионированной документации можно добавлять префиксы, например: v2-getting-started.mdx.

Индексные файлы

Файл с именем index.mdx выполняет особую функцию. Он автоматически используется как основной файл директории при импорте или маршрутизации:

docs/
 ├─ index.mdx
 ├─ installation.mdx
 └─ usage.mdx

В данном примере при рендеринге docs/ будет автоматически использован index.mdx. Это удобно для создания главных страниц разделов.

Импорт компонентов из файлов

MDX позволяет импортировать React-компоненты. Названия файлов компонентов, импортируемых в MDX, также критичны:

import { Button } from './components/Button';
import AlertMessage from './components/AlertMessage.mdx';
  • Компоненты должны иметь осмысленные имена, совпадающие с экспортируемым именем.
  • Использование .mdx расширения при импорте компонентов MDX обязательно, если файл не является частью сборки с поддержкой index.mdx.

Псевдонимы и alias

В больших проектах часто используют псевдонимы для сокращения путей:

import Header from '@components/Header';

Для корректной работы необходимо, чтобы структура файлов соответствовала заданному псевдониму. Ошибки в названиях файлов приведут к невозможности разрешить путь при сборке.

Разделение файлов по типу контента

Для удобства поддержки и навигации документации рекомендуется разбивать MDX-файлы по категориям:

docs/
 ├─ guides/
 │   ├─ getting-started.mdx
 │   └─ advanced-techniques.mdx
 ├─ api/
 │   ├─ authentication.mdx
 │   └─ data-fetching.mdx
 └─ index.mdx
  • guides/ — учебные материалы и примеры.
  • api/ — описание API и справочные материалы.
  • index.mdx — корневая страница документации.

Такое деление облегчает поддержку и позволяет инструментам генерации документации автоматически строить навигацию.

Влияние названия файла на маршрутизацию

В системах типа Next.js или Gatsby название MDX-файла формирует путь к странице:

  • Файл docs/getting-started.mdx → маршрут /docs/getting-started
  • Файл docs/index.mdx → маршрут /docs

Если требуется вложенный маршрут, создается директория с index.mdx внутри:

docs/
 └─ tutorials/
     └─ index.mdx

Маршрут будет /docs/tutorials.

Ограничения и лучшие практики

  • Избегать специальных символов и пробелов в названиях файлов.
  • Использовать нижний регистр и дефисы для единообразия.
  • Стараться, чтобы название файла отражало содержание документа.
  • Для файлов с кодом, примерами или компонентами использовать отдельную директорию, чтобы не смешивать документацию и функциональные файлы.

Заключение по организации файлов

Корректное именование MDX-файлов не только улучшает читаемость проекта, но и предотвращает ошибки при сборке и маршрутизации. Соблюдение соглашений о регистре, использовании дефисов и разделении по категориям позволяет создавать масштабируемую документацию и упрощает поддержку кода.

Оглавление