Czym jest MDX?

MDX to format, który pozwala pisać JSX bezpośrednio w dokumentach Markdown. Łączy prostotę Markdown w tworzeniu treści z możliwościami komponentów React, dzięki czemu jest popularny w witrynach dokumentacyjnych, blogach i aplikacjach z dużą ilością treści, budowanych przy użyciu frameworków takich jak Next.js, Gatsby i Docusaurus. Plik MDX może zawierać standardową składnię Markdown obok instrukcji import, eksportowanych zmiennych i wbudowanych komponentów JSX — wszystko w jednym pliku.

W przeciwieństwie do zwykłego Markdown, MDX jest kompilowany do JavaScript, co oznacza, że błędy składniowe w JSX lub instrukcjach import mogą uszkodzić cały dokument. Sprawia to, że walidacja i prawidłowe formatowanie są szczególnie ważne podczas pracy z treścią MDX.

Opis narzędzia

Edytor MDX zapewnia środowisko działające w przeglądarce do pisania, walidacji i formatowania treści MDX. Oferuje podświetlanie składni zarówno dla Markdown, jak i JSX, wbudowany walidator sprawdzający MDX pod kątem błędów kompilacji oraz formater porządkujący odstępy i strukturę, zapewniając spójne i czytelne dokumenty.

Przykłady

Przed formatowaniem:

import {Chart} from './components'
# Dashboard
Some intro text.


Extra blank lines here.
## Section
<Chart data={stats} />

Po formatowaniu:

import {Chart} from './components'

# Dashboard

Some intro text.

Extra blank lines here.

## Section

<Chart data={stats} />

Funkcje

  • Podświetlanie składni dla Markdown i JSX w jednym edytorze
  • Walidacja MDX sprawdzająca błędy kompilacji w czasie rzeczywistym
  • Automatyczne formatowanie normalizujące puste wiersze i odstępy
  • Przycisk czyszczenia umożliwiający szybkie zresetowanie edytora
  • Obsługa kopiowania ułatwiająca eksport sformatowanej treści

Jak to działa

  • Walidacja: Kompiluje treść MDX przy użyciu kompilatora @mdx-js/mdx. Jeśli dokument zawiera błędy składniowe — takie jak nieprawidłowy JSX, niezamknięte tagi lub nieprawidłowe importy — walidator wyświetla komunikat o błędzie, dzięki czemu można go naprawić.
  • Formatowanie: Normalizuje białe znaki, redukując wiele kolejnych pustych wierszy do jednego, zapewniając puste wiersze przed nagłówkami oraz wokół bloków import/export, a także usuwając końcowe białe znaki. Wynikiem jest czysty, spójnie ustrukturyzowany dokument.

Przypadki użycia

  • Pisanie dokumentacji dla projektów opartych na React, które używają MDX do stron z treścią
  • Debugowanie błędów kompilacji MDX przed wdrożeniem witryny statycznej
  • Porządkowanie plików MDX z niespójnymi odstępami, wprowadzonymi przez wielu autorów