Ссылки и изображения

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

Markdown-ссылки оформляются следующим образом:

[Текст ссылки](https://example.com)

Ключевые моменты:

  • Можно использовать абсолютные и относительные URL.
  • Для открытия ссылки в новой вкладке добавляется HTML-атрибут target="_blank" внутри JSX-версии ссылки. Markdown напрямую этого не поддерживает:
Текст ссылки
  • Атрибут rel="noopener noreferrer" обязателен при использовании target="_blank" для предотвращения утечек контекста страницы и повышения безопасности.

Ссылки на внутренние страницы сайта оформляются как относительные пути:

[Документация](./docs/introduction)

При использовании MDX в рамках Next.js или Gatsby для внутренних ссылок часто применяются компоненты Link, чтобы сохранялась маршрутизация без перезагрузки страницы:

import Link from 'next/link';

Документация

Изображения в MDX

MDX поддерживает стандартный синтаксис Markdown для изображений:

![Альтернативный текст](./images/example.png)

Особенности работы с изображениями:

  • Альтернативный текст обязателен для доступности, SEO и корректного отображения при недоступности ресурса.
  • Относительные пути удобны при хранении изображений рядом с MDX-файлом.
  • JSX-версии изображений позволяют использовать атрибуты width, height, style и кастомные свойства:
Описание изображения
  • В проектах на Next.js предпочтительно использовать компонент next/image для оптимизации загрузки, поддержки lazy loading и автоматического ресайза:
import Image from 'next/image';
import exampleImg from './images/example.png';

Описание изображения

Комбинирование ссылок и изображений

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

[![Логотип](./images/logo.png)](https://example.com)

Или через JSX для расширенной кастомизации:


  Логотип

Динамические ссылки и изображения через переменные

MDX позволяет использовать переменные для динамического формирования ссылок и изображений. Например:

const linkUrl = "https://example.com";
const imageUrl = "./images/example.png";


  Динамическое изображение

Такой подход особенно полезен при генерации контента с данными из API или при повторном использовании компонентов.

Поддержка компонентов с оберткой

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

const StyledLink = ({ href, children }) => (
  
    {children}
  
);

const StyledImage = ({ src, alt }) => (
  {alt}
);

Использование:

Такой подход обеспечивает единый стиль и упрощает поддержку проекта при большом количестве контента.

SEO и доступность

При работе с ссылками и изображениями важно соблюдать следующие правила:

  • Все изображения должны иметь alt.
  • Ссылки должны быть понятными без контекста текста (например, вместо «кликните здесь» использовать «Смотреть документацию»).
  • Использовать rel="noopener noreferrer" для внешних ссылок с target="_blank".
  • При необходимости можно добавлять title для ссылок и изображений для дополнительного пояснения:
[Документация](./docs/introduction "Перейти к документации")

Эти правила не только повышают удобство пользователей, но и влияют на ранжирование страниц поисковыми системами.

Оглавление