Creation:2025-02-07Last update:2026-05-19

    Markdown / Вміст форматованого тексту

    Intlayer підтримує вміст форматованого тексту, визначений за допомогою синтаксису Markdown. Це дозволяє легко створювати та підтримувати форматований вміст, такий як блоги, статті тощо.

    Оголошення вмісту Markdown

    Ви можете оголосити вміст Markdown за допомогою функції md або просто як рядок (якщо він містить синтаксис Markdown).

    Починаючи з версії 8.10.0, ви можете оголошувати вміст Markdown безпосередньо у файлах .content.md. Intlayer автоматично виявлятиме та аналізуватиме вміст Markdown.

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: Мій вмістlocale: en---# Мій вмістОсь приклад вмісту markdown

    Поле front-matter locale визначає локаль вмісту. Воно є необов'язковим. Якщо його не вказано, Intlayer використовуватиме локаль за замовчуванням, яка також слугуватиме резервною, якщо переклад для конкретної локалі недоступний.

    Приклад структури файлів:

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

    У front-matter ви можете додати будь-які властивості, визначені у Визначенні словника

    Рендеринг Markdown

    Intlayer надає два незалежні способи рендерингу Markdown:

    1. Через useIntlayer — Intlayer автоматично перетворює вузол md у нативний вихідний формат фреймворку (JSX, VNode, HTML-рядок).

      • Frontmatter аналізується та надається як .metadata. Ви можете перевизначити рендеринг на двох рівнях — глобально за допомогою MarkdownProvider (або еквівалента фреймворку) та локально для кожного вузла за допомогою .use(). Обидва підходи можна комбінувати; .use() має пріоритет над MarkdownProvider, який має пріоритет над поведінкою за замовчуванням.

    2. Допоміжні утиліти — <MarkdownRenderer />, useMarkdownRenderer() та renderMarkdown() є самостійними інструментами, які приймають тільки необроблені рядки Markdown. Вони не залежать від useIntlayer і не працюють з оформленими вузлами, які він повертає.

    Рендеринг Markdown підтримує MDX — використовуйте будь-який компонент JSX/фреймворку за назвою безпосередньо у вашому Markdown.

    1. Автоматичний рендеринг (через useIntlayer)

    Вузли Markdown можна рендерити безпосередньо як 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} />, // MDX-компонент    }}  >    <AppContent />  </MarkdownProvider>);
    Якщо MarkdownProvider відсутній, Intlayer рендеритиме markdown, використовуючи стандартний парсер Markdown у JSX.

    Ви також можете надати локальні перевизначення для конкретних вузлів за допомогою методу .use():

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

    Ви можете отримати Markdown як рядок:

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

    І ви можете отримати доступ до метаданих markdown наступним чином:

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

    2. Допоміжні утиліти (тільки рядки Markdown)

    Ці утиліти рендерять тільки необроблені рядки Markdown і не залежать від useIntlayer. Використовуйте їх, коли вам потрібно відрендерити Markdown з джерел, відмінних від ваших словників.

    Компонент <MarkdownRenderer />

    Рендерить рядок Markdown з певними опціями.

    tsx
    import { MarkdownRenderer } from "react-intlayer/markdown";<MarkdownRenderer forceBlock={true} tagfilter={true}>  {"# Мій Заголовок"}</MarkdownRenderer>

    Хук useMarkdownRenderer()

    Отримайте попередньо налаштовану функцію рендерингу.

    tsx
    import { useMarkdownRenderer } from "react-intlayer/markdown";const renderMarkdown = useMarkdownRenderer({  forceBlock: true,  components: { h1: (props) => <h1 {...props} className="custom" /> }});return renderMarkdown("# Мій Заголовок");

    Утиліта renderMarkdown()

    Окрема утиліта для рендерингу поза компонентами.

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# Мій Заголовок", { forceBlock: true });

    Глобальне налаштування за допомогою MarkdownProvider

    MarkdownProvider (або його еквівалент у фреймворку) налаштовує конвеєр рендерингу Markdown для всього вашого додатку. Це стосується як автоматичного рендерингу useIntlayer, так і допоміжних утиліт. Налаштування, вказані тут, є значеннями за замовчуванням — .use() перевизначає їх на рівні вузла.

    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 — будь-яка назва компонента, яка використовується всередині вашого Markdown (наприклад, <MyCustomJSXComponent />), розпізнається відповідно до карти components.

    Ви також можете використовувати власний рендерер 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>);
    Динамічний імпорт вашого рендерера Markdown — чудовий спосіб зменшити розмір бандлу вашого додатка.

    Suspense

    Рендерер Markdown Intlayer завантажується динамічно. Хоча він оптимізований, базовий фрагмент аналізатора становить близько 55 кБ. Синхронне завантаження цього затримує початковий рендеринг сторінки та погіршує First Contentful Paint (FCP).

    Щоб запобігти блокуванню інтерфейсу користувача, Intlayer інтегрується з API Suspense від React. Він завантажує аналізатор у фоновому режимі та створює Promise під час завантаження.

    Оберніть будь-який компонент, що відображає Intlayer Markdown, у межу <Suspense>. Це показує локалізований резервний стан під час завантаження фрагмента, дозволяючи решті вашого DOM відображатися негайно.

    Попередження: Якщо ви не надасте межу <Suspense>, React призупинить рендеринг на кореневому рівні або заблокує рендеринг всього дерева компонентів, доки фрагмент у 55 кБ не буде повністю завантажений.

    У маршрутизаторі Next.js App Router ви можете використовувати або React Suspense для клієнтських компонентів, або файл loading.tsx для серверних компонентів.

    Клієнтський компонент:

    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>);};

    Серверний компонент з 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;

    Рендеринг на стороні сервера (SSR) та гідратація

    У порівнянні з іншими парсерами Markdown, такими як remark / rehype, Intlayer Markdown не має залежностей і працює як на клієнті, так і на сервері.

    Однак Intlayer оптимізує синтаксичний аналіз для фреймворків серверного рендерингу (SSR) (таких як Next.js App Router, React Router, Nuxt, SvelteKit тощо).

    Замість надсилання необроблених рядків Markdown клієнту та їх аналізу в браузері (що призводить до зниження продуктивності), Intlayer дозволяє попередньо проаналізувати Markdown в абстрактне синтаксичне дерево (AST) на сервері.

    Ви можете використовувати функцію parseMarkdown з пакету Intlayer вашого фреймворку на стороні сервера для генерації серіалізованого AST (об'єкта ParsedMarkdown) і передачі його безпосередньо на фронтенд. Всі утиліти рендерингу Intlayer (такі як <MarkdownRenderer>, useMarkdownRenderer тощо) автоматично приймають цей об'єкт AST і плавно рендерять його.

    Приклад в архітектурі Сервер/Клієнт

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. На сервері: перетворити markdown на серіалізоване ASTexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // Повернути AST клієнту у форматі JSON  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. На клієнті: відрендерити AST безпосередньо без повторного аналізуexport default function Page() {  const { content } = useLoaderData();  // Рендерер приймає або необроблений рядок, або проаналізоване AST  return <MarkdownRenderer content={content} />;}

    Цей підхід гарантує, що логіка аналізу Markdown повністю виконується на сервері, що значно скорочує час виконання на стороні клієнта та підвищує швидкість початкової гідратації.

    Довідник опцій

    Ці параметри можна передати до MarkdownProvider, MarkdownRenderer, useMarkdownRenderer та renderMarkdown.

    Option Type Default Опис
    forceBlock boolean false Примушує вивід обгортатися блочним елементом (наприклад, <div>).
    forceInline boolean false Примушує вивід обгортатися вбудованим елементом (наприклад, <span>).
    tagfilter boolean true Увімкнює фільтр тегів GitHub для підвищення безпеки шляхом видалення небезпечних тегів HTML.
    preserveFrontmatter boolean false Якщо true, початкові метадані (frontmatter) на початку рядка Markdown не будуть видалені.
    components Overrides {} Карта тегів HTML до власних компонентів (наприклад, { h1: MyHeading }).
    wrapper Component null Спеціальний компонент для обгортання відображеного Markdown.
    renderMarkdown Function null Власна функція рендерингу для повної заміни компілятора Markdown за замовчуванням.
    Вкладеність
    HTML