Autor: Aymeric PINEAU
    Data utworzenia:2025-02-07Ostatnia aktualizacja:2026-05-19

    Markdown / Treść w postaci tekstu sformatowanego

    Intlayer obsługuje treści w postaci tekstu sformatowanego (Rich Text) definiowane za pomocą składni Markdown. Pozwala to na łatwe pisanie i utrzymywanie bogato sformatowanych treści, takich jak blogi, artykuły i inne.

    Deklarowanie treści Markdown

    Możesz zadeklarować treść Markdown używając funkcji md lub po prostu jako ciąg znaków (jeśli zawiera składnię Markdown).

    Począwszy od wersji 8.10.0, możesz deklarować treść Markdown bezpośrednio w plikach .content.md. Intlayer automatycznie wykryje i przetworzy treść Markdown.

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: Moja treśćlocale: en---# Moja treśćOto przykład treści markdown

    Pole front-matter locale to pole, które definiuje język treści. Jest ono opcjonalne. Jeśli nie zostanie podane, Intlayer użyje języka domyślnego, który służy również jako język zastępczy, jeśli nie jest dostępne tłumaczenie dla określonego języka.

    Przykład struktury plików:

    text
    content├── markdown-file.en.content.md├── markdown-file.fr.content.md└── markdown-file.es.content.md

    Do front-matter można dodać dowolne właściwości zdefiniowane w Definicji słownika

    Renderowanie Markdown

    Intlayer zapewnia dwa niezależne sposoby renderowania Markdown:

    1. Przez useIntlayer — Intlayer automatycznie przekształca węzeł md w natywny wynik frameworka (JSX, VNode, ciąg znaków HTML).

      • Frontmatter jest analizowany i eksponowany jako .metadata. Możesz nadpisać renderowanie na dwóch poziomach — globalnie za pomocą MarkdownProvider (lub odpowiednika frameworka) i lokalnie dla węzła za pomocą .use(). Oba można łączyć; .use() ma pierwszeństwo przed MarkdownProvider, który z kolei ma pierwszeństwo przed ustawieniami domyślnymi.

    2. Narzędzia pomocnicze — <MarkdownRenderer />, useMarkdownRenderer() i renderMarkdown() to samodzielne narzędzia, które akceptują tylko surowe ciągi znaków Markdown. Są one niezależne od useIntlayer i nie działają ze zwracanymi przez nie udekorowanymi węzłami.

    Renderowanie Markdown obsługuje MDX — użyj dowolnego komponentu JSX/frameworka podając jego nazwę bezpośrednio w swoim Markdown.

    1. Automatyczne renderowanie (przez useIntlayer)

    Węzły Markdown można renderować bezpośrednio jako JSX.

    App.tsx
    import { useIntlayer } from "react-intlayer";import { MarkdownProvider } from "react-intlayer/markdown";const AppContent = () => {  const { myMarkdownContent } = useIntlayer("app");  return <div>{myMarkdownContent}</div>;};const App = () => (  <MarkdownProvider    components={{      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,      MyButton: (props) => <button {...props} />, // Komponent MDX    }}  >    <AppContent />  </MarkdownProvider>);
    Jeśli MarkdownProvider nie jest obecny, Intlayer użyje domyślnego parsera Markdown do JSX do wyrenderowania markdownu.

    Możesz również zapewnić lokalne nadpisania dla określonych węzłów za pomocą metody .use():

    tsx
    {myMarkdownContent.use({  h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,})}

    Możesz pobrać Markdown jako ciąg znaków:

    tsx
    {myMarkdownContent.value}{String(myMarkdownContent)}{myMarkdownContent.toString()}

    Możesz uzyskać dostęp do metadanych markdown w ten sposób:

    tsx
    {myMarkdownContent.metadata}{myMarkdownContent.metadata.title}

    2. Narzędzia pomocnicze (tylko ciągi znaków Markdown)

    Te narzędzia renderują tylko surowe ciągi znaków Markdown i są niezależne od useIntlayer. Używaj ich, gdy musisz wyrenderować Markdown ze źródeł innych niż słowniki.

    Komponent <MarkdownRenderer />

    Renderuje ciąg znaków Markdown z określonymi opcjami.

    tsx
    import { MarkdownRenderer } from "react-intlayer/markdown";<MarkdownRenderer forceBlock={true} tagfilter={true}>  {"# Mój Tytuł"}</MarkdownRenderer>

    Hook useMarkdownRenderer()

    Pobierz wstępnie skonfigurowaną funkcję renderowania.

    tsx
    import { useMarkdownRenderer } from "react-intlayer/markdown";const renderMarkdown = useMarkdownRenderer({  forceBlock: true,  components: { h1: (props) => <h1 {...props} className="custom" /> }});return renderMarkdown("# Mój Tytuł");

    Narzędzie renderMarkdown()

    Samodzielne narzędzie do renderowania poza komponentami.

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# Mój Tytuł", { forceBlock: true });

    Konfiguracja globalna z MarkdownProvider

    MarkdownProvider (lub jego odpowiednik we frameworku) konfiguruje potok renderowania Markdown dla całej aplikacji. Dotyczy to zarówno automatycznego renderowania useIntlayer, jak i narzędzi pomocniczych. Ustawione tutaj opcje są ustawieniami domyślnymi — .use() nadpisuje je na poziomie węzła.

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    components={{      h1: (props) => <h1 style={{color: 'green'}} {...props} />,      a: ({ href, ...props }) => <a style={{color: 'red'}} {...props} />,      MyCustomJSXComponent: (props) => <span style={{color: 'red'}} {...props} />,    }}  >    {children}  </MarkdownProvider>);
    MDX jest obsługiwany — każda nazwa komponentu użyta wewnątrz twojego Markdown (np. <MyCustomJSXComponent />) jest rozwiązywana względem mapy components.

    Możesz również użyć własnego renderera markdown:

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    renderMarkdown={async (md) => {      // Use dynamic import to reduce the bundle size of your application      const { renderMarkdown } = await import('react-intlayer/markdown');      return renderMarkdown(md);    }}  >    {children}  </MarkdownProvider>);
    Dynamiczne importowanie twojego renderera Markdown to świetny sposób na zmniejszenie rozmiaru pakietu twojej aplikacji.

    Suspense

    Renderer Markdown Intlayer jest ładowany dynamicznie. Mimo optymalizacji, bazowy fragment parsera zajmuje około 55 kb. Synchroniczne ładowanie tego opóźnia początkowe renderowanie strony i pogarsza First Contentful Paint (FCP).

    Aby zapobiec blokowaniu interfejsu użytkownika, Intlayer integruje się z API Suspense Reacta. Pobiera parser w tle i rzuca Promise podczas pobierania.

    Zawiń dowolny komponent renderujący Intlayer Markdown w granicę <Suspense>. Wyświetli to zlokalizowany stan rezerwowy podczas pobierania fragmentu, umożliwiając natychmiastowe renderowanie reszty DOM.

    Ostrzeżenie: Jeśli nie zapewnisz granicy <Suspense>, React wstrzyma działanie na poziomie głównym lub zablokuje renderowanie całego drzewa komponentów do czasu pełnego załadowania 55 kb fragmentu.

    W Next.js App Router można użyć React Suspense dla komponentów klienckich lub pliku loading.tsx dla komponentów serwerowych.

    Komponent kliencki:

    components/MyComponent.tsx
    "use client";import { useIntlayer } from "next-intlayer";import { Suspense } from "react";const MyComponent = () => {const markdownContent = useIntlayer("my-markdown");return (  <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>);};

    Komponent serwerowy z loading.tsx:

    app/loading.tsx
    export default function Loading() {return <div>Loading...</div>;}
    app/page.tsx
    import { useIntlayer } from "next-intlayer/server";const MyPage = () => {const markdownContent = useIntlayer("my-markdown");return <div>{markdownContent}</div>;};export default MyPage;

    Renderowanie po stronie serwera (SSR) i hydratacja

    W porównaniu do innych parserów Markdown, takich jak remark / rehype, Intlayer Markdown jest pozbawiony zależności i działa zarówno po stronie klienta, jak i serwera.

    Jednak Intlayer optymalizuje parsowanie dla frameworków renderowania po stronie serwera (SSR) (takich jak Next.js App Router, React Router, Nuxt, SvelteKit itp.).

    Zamiast wysyłać surowe ciągi Markdown do klienta i parsować je w przeglądarce (co powoduje spadek wydajności), Intlayer pozwala na wstępne sparsowanie Markdown do abstrakcyjnego drzewa składniowego (AST) na serwerze.

    Możesz użyć funkcji parseMarkdown z pakietu Intlayer swojego frameworka po stronie serwera, aby wygenerować serializowalne AST (obiekt ParsedMarkdown) i przekazać je bezpośrednio do frontendu. Wszystkie narzędzia renderujące Intlayer (takie jak <MarkdownRenderer>, useMarkdownRenderer itp.) automatycznie akceptują ten obiekt AST i renderują go bez zakłóceń.

    Przykład w architekturze serwer/klient

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. Na serwerze: Sparsuj markdown do serializowalnego ASTexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // Zwróć AST jako JSON do klienta  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. Na kliencie: Renderuj AST bezpośrednio bez ponownego parsowaniaexport default function Page() {  const { content } = useLoaderData();  // Renderer akceptuje surowy ciąg znaków lub sparsowane AST  return <MarkdownRenderer content={content} />;}

    Ten wzorzec zapewnia, że logika parsowania Markdown jest wykonywana całkowicie na serwerze, co znacznie skraca czas wykonywania po stronie klienta i poprawia szybkość początkowej hydratacji.

    Opcje referencyjne

    Te opcje można przekazać do MarkdownProvider, MarkdownRenderer, useMarkdownRenderer i renderMarkdown.

    Option Type Default Opis
    forceBlock boolean false Wymusza zawijanie wyjścia w element blokowy (np. <div>).
    forceInline boolean false Wymusza zawijanie wyjścia w element liniowy (np. <span>).
    tagfilter boolean true Włącza GitHub Tag Filter w celu zwiększenia bezpieczeństwa poprzez usuwanie niebezpiecznych tagów HTML.
    preserveFrontmatter boolean false Jeśli true, frontmatter na początku ciągu Markdown nie zostanie usunięty.
    components Overrides {} Mapa tagów HTML na niestandardowe komponenty (np. { h1: MyHeading }).
    wrapper Component null Niestandardowy komponent do zawijania renderowanego Markdown.
    renderMarkdown Function null Niestandardowa funkcja renderowania, aby całkowicie zastąpić domyślny kompilator Markdown.
    ZagnieżdżanieHTML