Комментарии в MDX документах

MDX сочетает возможности Markdown и JSX, позволяя создавать динамический контент, включающий компоненты React прямо внутри документации. Комментарии в MDX играют ключевую роль для организации кода, пояснений и временного отключения частей документа без их удаления.

Комментарии Markdown

В MDX поддерживаются стандартные комментарии Markdown:

<!-- Этот комментарий не будет отображён на странице -->

Особенности:

  • Комментарий начинается с <!-- и заканчивается на -->.
  • Любой текст между этими тегами игнорируется рендерером.
  • Подходит для статических пояснений, инструкций и временного скрытия блоков Markdown.
  • Не может содержать вложенные <!-- --> конструкции — это приведёт к ошибкам парсинга.

Пример использования:

# Заголовок

<!-- TODO: Добавить пример использования компонента Button -->

Текст документации здесь.

Комментарии в JSX частях MDX

Так как MDX поддерживает JSX, внутри блоков кода React можно использовать стандартные JSX-комментарии:

{
  /* Этот комментарий виден только в исходном коде, не на странице */
}

Особенности:

  • Используется синтаксис {/* комментарий */}.
  • Можно вставлять в любом месте JSX-разметки, включая внутри тегов и выражений.
  • Поддерживается многострочный текст, что удобно для длинных пояснений.

Пример:

import { Button } from './components/Button'

<Button onCl ick={() => console.log('Clicked')}>
  Click me
  {/* Здесь мы добавляем комментарий, объясняющий поведение */}
</Button>

Временное отключение кода и компонентов

Комментарии можно использовать для временного исключения частей кода из рендеринга:

<!--
<Button onCl ick={() => alert('Disabled')}>
  Не отображается
</Button>
-->

или в JSX:

{
  /*
  <Button onCl ick={() => alert('Disabled')}>
    Не отображается
  </Button>
  */
}

Разница заключается в том, что Markdown-комментарии полностью игнорируются парсером Markdown, а JSX-комментарии работают только внутри JSX-блоков.

Комментарии в комбинации Markdown и JSX

MDX позволяет смешивать Markdown и JSX, поэтому важно понимать, где какой комментарий применяется. Пример:

# Пример MDX

<!-- Это Markdown-комментарий -->

<Button>
  Click
  {/* Это JSX-комментарий */}
</Button>
  • Markdown-комментарий не рендерится и не влияет на JSX.
  • JSX-комментарий работает только внутри JSX-блоков и не затрагивает текст Markdown.

Советы по использованию комментариев

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

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

Оглавление