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-контента

    Поле locale в front-matter определяет локаль контента. Оно необязательно. Если оно не указано, Intlayer будет использовать локаль по умолчанию, которая также используется в качестве резервной локали (fallback), если перевод для конкретной локали недоступен.

    Пример структуры файлов:

    text
    content/├── en/│   └── markdown-file.en.content.md├── fr/│   └── markdown-file.fr.content.md└── es/    └── 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 (raw strings). Они не зависят от 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}

    Suspense

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

    Чтобы предотвратить блокировку пользовательского интерфейса, Intlayer интегрируется с API React Suspense. Он загружает парсер в фоновом режиме и выдает 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