Autor: Aymeric PINEAU
    Criação:2025-02-07Última atualização:2026-05-19

    Markdown / Conteúdo de Texto Rico

    O Intlayer suporta conteúdo de texto rico definido usando a sintaxe Markdown. Isso permite que você escreva e mantenha facilmente conteúdos com formatação rica, como blogs, artigos e muito mais.

    Declarando Conteúdo Markdown

    Você pode declarar conteúdo Markdown usando a função md ou simplesmente como uma string (se ela contiver sintaxe Markdown).

    A partir da versão 8.10.0, você pode declarar conteúdo Markdown diretamente em arquivos .content.md. O Intlayer detectará e processará automaticamente o conteúdo Markdown.

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: Meu conteúdolocale: en---# Meu conteúdoAqui está um exemplo de conteúdo markdown

    O campo locale no front-matter é o campo que define a localização do conteúdo. É opcional. Se não for fornecido, o Intlayer usará o idioma padrão, que também é usado como idioma de fallback caso não haja tradução disponível para um idioma específico.

    Exemplo de estrutura de diretórios:

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

    Você pode adicionar no front-matter quaisquer propriedades definidas na Definição de Dicionário

    Renderizando Markdown

    O Intlayer fornece duas maneiras independentes de renderizar Markdown:

    1. Através do useIntlayer — O Intlayer transforma automaticamente o nó md na saída nativa do framework (JSX, VNode, string HTML).

      • O Frontmatter é analisado e exposto como .metadata. Você pode substituir a renderização em dois níveis — globalmente com MarkdownProvider (ou o equivalente do framework) e localmente por nó com .use(). Ambos podem ser combinados; .use() tem prioridade sobre MarkdownProvider, que por sua vez tem prioridade sobre o padrão.

    2. Utilitários auxiliares — <MarkdownRenderer />, useMarkdownRenderer() e renderMarkdown() são ferramentas autônomas que aceitam apenas strings Markdown brutas. Elas são independentes do useIntlayer e não funcionam com os nós decorados que ele retorna.

    A renderização do Markdown suporta MDX — use qualquer componente JSX/framework por nome diretamente no seu Markdown.

    1. Renderização Automática (através de useIntlayer)

    Nós Markdown podem ser renderizados diretamente como 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} />, // Componente MDX    }}  >    <AppContent />  </MarkdownProvider>);
    Se o MarkdownProvider não estiver presente, o Intlayer renderizará o markdown usando o parser padrão Markdown-para-JSX.

    Você também pode fornecer substituições locais para nós específicos usando o método .use():

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

    Você pode recuperar o Markdown como string:

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

    E você pode acessar os metadados do markdown assim:

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

    2. Utilitários auxiliares (Somente Strings Markdown)

    Estes utilitários renderizam apenas strings Markdown brutas e são independentes do useIntlayer. Use-os quando precisar renderizar Markdown de fontes além de seus dicionários.

    Componente <MarkdownRenderer />

    Renderiza uma string Markdown com opções específicas.

    tsx
    import { MarkdownRenderer } from "react-intlayer/markdown";<MarkdownRenderer forceBlock={true} tagfilter={true}>  {"# Meu Título"}</MarkdownRenderer>

    Hook useMarkdownRenderer()

    Obtém uma função de renderização pré-configurada.

    tsx
    import { useMarkdownRenderer } from "react-intlayer/markdown";const renderMarkdown = useMarkdownRenderer({  forceBlock: true,  components: { h1: (props) => <h1 {...props} className="custom" /> }});return renderMarkdown("# Meu Título");

    Utilitário renderMarkdown()

    Utilitário autônomo para renderização fora dos componentes.

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# Meu Título", { forceBlock: true });

    Configuração Global com MarkdownProvider

    O MarkdownProvider (ou o seu equivalente do framework) configura o pipeline de renderização Markdown para toda a sua aplicação. Aplica-se tanto para a renderização automática do useIntlayer quanto para os utilitários auxiliares. Opções definidas aqui são os padrões — o .use() substitui-os em nível de nó.

    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>);
    O MDX é suportado — qualquer nome de componente usado dentro do seu Markdown (ex: <MyCustomJSXComponent />) é resolvido com base no mapa de components.

    Você também pode usar seu próprio renderizador de 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>);
    Importar dinamicamente o seu renderizador de Markdown é uma ótima maneira de reduzir o tamanho do bundle da sua aplicação.

    Suspense

    O renderizador Markdown do Intlayer é carregado dinamicamente. Embora otimizado, o chunk do analisador subjacente tem aproximadamente 55 kb. Carregar isso de forma síncrona atrasa a renderização inicial da página e degrada o First Contentful Paint (FCP).

    Para evitar o bloqueio da interface do usuário, o Intlayer se integra com a API Suspense do React. Ele busca o analisador em segundo plano e lança uma Promise durante o download.

    Envolva qualquer componente que renderize o Intlayer Markdown em um limite <Suspense>. Isso exibe um estado de fallback localizado enquanto o chunk é baixado, permitindo que o restante de seu DOM seja renderizado imediatamente.

    Aviso: Se você não fornecer um limite <Suspense>, o React irá suspender no nível raiz ou bloquear a renderização de toda a árvore de componentes até que o chunk de 55 kb seja totalmente carregado.

    No Next.js App Router, você pode usar o React Suspense para componentes do cliente ou um arquivo loading.tsx para componentes do servidor.

    Componente do Cliente:

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

    Componente do Servidor com 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;

    Renderização no Lado do Servidor (SSR) e Hidratação

    Em comparação com outros analisadores de Markdown, como remark / rehype, o Intlayer Markdown é livre de dependências e roda tanto no cliente quanto no servidor.

    No entanto, o Intlayer otimiza a análise para frameworks de Renderização no Lado do Servidor (SSR) (como Next.js App Router, React Router, Nuxt, SvelteKit, etc.).

    Em vez de enviar strings Markdown brutas para o cliente e analisá-las no navegador (o que acarreta uma perda de desempenho), o Intlayer permite pré-analisar o Markdown em uma Árvore de Sintaxe Abstrata (AST) no servidor.

    Você pode usar a função parseMarkdown do pacote Intlayer do seu framework no lado do servidor para gerar uma AST serializável (objeto ParsedMarkdown) e passá-la diretamente para o frontend. Todos os utilitários de renderização do Intlayer (como <MarkdownRenderer>, useMarkdownRenderer, etc.) aceitam automaticamente esse objeto AST e o renderizam perfeitamente.

    Exemplo em uma Arquitetura Servidor/Cliente

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. No servidor: Analisar o markdown em uma AST serializávelexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // Retornar a AST como JSON para o cliente  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. No cliente: Renderizar a AST diretamente sem reanalisarexport default function Page() {  const { content } = useLoaderData();  // O renderizador aceita uma string bruta ou a AST analisada  return <MarkdownRenderer content={content} />;}

    Esse padrão garante que a lógica de análise do Markdown seja executada inteiramente no servidor, reduzindo significativamente o tempo de execução no cliente e melhorando a velocidade de hidratação inicial.

    Referência de opções

    Essas opções podem ser passadas para MarkdownProvider, MarkdownRenderer, useMarkdownRenderer e renderMarkdown.

    Option Type Default Descrição
    forceBlock boolean false Força a saída a ser envolvida em um elemento de nível de bloco (ex: <div>).
    forceInline boolean false Força a saída a ser envolvida em um elemento em linha (ex: <span>).
    tagfilter boolean true Habilita o GitHub Tag Filter para melhor segurança removendo tags HTML perigosas.
    preserveFrontmatter boolean false Se true, o frontmatter no início da string Markdown não será removido.
    components Overrides {} Um mapa de tags HTML para componentes personalizados (ex: { h1: MyHeading }).
    wrapper Component null Um componente personalizado para envolver o Markdown renderizado.
    renderMarkdown Function null Uma função de renderização personalizada para substituir completamente o compilador Markdown padrão.
    AninhamentoHTML