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

    Markdown / Contenido de Texto Enriquecido

    Intlayer admite contenido de texto enriquecido definido mediante la sintaxis Markdown. Esto le permite escribir y mantener fácilmente contenido con formato enriquecido, como blogs, artículos y mucho más.

    Declarar Contenido Markdown

    Puede declarar contenido Markdown usando la función md o simplemente como una cadena de texto (si contiene sintaxis Markdown).

    A partir de la versión 8.10.0, puede declarar contenido Markdown directamente en archivos .content.md. Intlayer detectará y analizará automáticamente el contenido Markdown.

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: Mi contenidolocale: en---# Mi contenidoAquí hay un ejemplo de contenido markdown

    El campo locale en el front-matter es el campo que define el idioma del contenido. Es opcional. Si no se proporciona, Intlayer utilizará el idioma por defecto, que también se usa como idioma de respaldo si no hay traducción disponible para un idioma específico.

    Ejemplo de estructura de archivos:

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

    Puede agregar en el front-matter cualquier propiedad definida en la Definición del Diccionario

    Renderización de Markdown

    Intlayer proporciona dos formas independientes de renderizar Markdown:

    1. A través de useIntlayer — Intlayer transforma automáticamente el nodo md en la salida nativa del framework (JSX, VNode, cadena HTML).

      • El Frontmatter se analiza y expone como .metadata. Puede anular la renderización en dos niveles — globalmente con MarkdownProvider (o el equivalente en el framework) y localmente por nodo con .use(). Ambos pueden combinarse; .use() tiene prioridad sobre MarkdownProvider, el cual tiene prioridad sobre el predeterminado.

    2. Utilidades auxiliares — <MarkdownRenderer />, useMarkdownRenderer(), y renderMarkdown() son herramientas independientes que aceptan únicamente cadenas Markdown puras. Son independientes de useIntlayer y no funcionan con los nodos decorados que este retorna.

    La renderización de Markdown admite MDX — use cualquier componente JSX/framework por su nombre directamente dentro de su Markdown.

    1. Renderización Automática (a través de useIntlayer)

    Los nodos Markdown se pueden renderizar directamente 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>);
    Si MarkdownProvider no está presente, Intlayer renderizará el markdown usando el analizador por defecto de Markdown a JSX.

    También puede proporcionar anulaciones locales para nodos específicos utilizando el método .use():

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

    Puede recuperar el Markdown como cadena:

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

    Y puede acceder a los metadatos de su markdown así:

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

    2. Utilidades Auxiliares (Solo Cadenas Markdown)

    Estas utilidades renderizan únicamente cadenas Markdown puras y son independientes de useIntlayer. Úselas cuando necesite renderizar Markdown de fuentes que no sean sus diccionarios.

    Componente <MarkdownRenderer />

    Renderiza una cadena Markdown con opciones específicas.

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

    Hook useMarkdownRenderer()

    Obtenga una función de renderizado preconfigurada.

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

    Utilidad renderMarkdown()

    Utilidad independiente para renderizar fuera de los componentes.

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

    Configuración Global con MarkdownProvider

    MarkdownProvider (o su equivalente en el framework) configura el proceso de renderización Markdown para toda su aplicación. Esto se aplica tanto a la renderización automática de useIntlayer como a las utilidades auxiliares. Las opciones configuradas aquí son las predeterminadas — .use() las anula a nivel de nodo.

    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 es compatible — cualquier nombre de componente usado dentro de su Markdown (ej. <MyCustomJSXComponent />) se resuelve contra el mapeo de components.

    También puede usar su propio 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 su renderizador de Markdown dinámicamente es una buena manera de reducir el tamaño del bundle de su aplicación.

    Suspense

    El renderizador de Markdown de Intlayer se carga dinámicamente. Aunque está optimizado, el fragmento (chunk) del analizador subyacente es de aproximadamente 55 kb. Cargar esto sincrónicamente retrasa la representación inicial de la página y degrada el First Contentful Paint (FCP).

    Para evitar el bloqueo de la interfaz de usuario, Intlayer se integra con la API Suspense de React. Recupera el analizador en segundo plano y arroja una Promesa durante la descarga.

    Envuelva cualquier componente que represente Intlayer Markdown en un límite <Suspense>. Esto muestra un estado de retroceso localizado mientras se descarga el fragmento, permitiendo que el resto de su DOM se represente de inmediato.

    Advertencia: Si no proporciona un límite <Suspense>, React suspenderá en el nivel raíz o bloqueará la representación de todo el árbol de componentes hasta que el fragmento de 55 kb esté completamente cargado.

    En Next.js App Router, puede usar React Suspense para componentes del cliente o un archivo loading.tsx para componentes del servidor.

    Componente de 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 de servidor con 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;

    Renderizado en el Lado del Servidor (SSR) e Hidratación

    En comparación con otros analizadores de Markdown como remark / rehype, Intlayer Markdown no tiene dependencias y se ejecuta tanto en el cliente como en el servidor.

    Sin embargo, Intlayer optimiza el análisis para frameworks de renderizado en el lado del servidor (SSR) (como Next.js App Router, React Router, Nuxt, SvelteKit, etc.).

    En lugar de enviar cadenas Markdown crudas al cliente y analizarlas en el navegador (lo que incurre en una penalización de rendimiento), Intlayer le permite preanalizar el Markdown en un Árbol de Sintaxis Abstracta (AST) en el servidor.

    Puede usar la función parseMarkdown del paquete Intlayer de su framework en el lado del servidor para generar un AST serializable (objeto ParsedMarkdown) y pasarlo directamente al frontend. Todas las utilidades de renderizado de Intlayer (como <MarkdownRenderer>, useMarkdownRenderer, etc.) aceptan automáticamente este objeto AST y lo renderizan sin problemas.

    Ejemplo en una Arquitectura Servidor/Cliente

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. En el servidor: Analizar el markdown en un AST serializableexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // Devolver el AST como JSON al cliente  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. En el cliente: Renderizar el AST directamente sin volver a analizarexport default function Page() {  const { content } = useLoaderData();  // El renderizador acepta tanto una cadena cruda como el AST analizado  return <MarkdownRenderer content={content} />;}

    Este patrón garantiza que la lógica de análisis de Markdown se ejecute completamente en el servidor, lo que reduce significativamente el tiempo de ejecución en el cliente y mejora la velocidad de hidratación inicial.

    Referencia de opciones

    Estas opciones se pueden pasar a MarkdownProvider, MarkdownRenderer, useMarkdownRenderer y renderMarkdown.

    Option Type Default Descripción
    forceBlock boolean false Fuerza la salida para que esté envuelta en un elemento de nivel de bloque (ej. <div>).
    forceInline boolean false Fuerza la salida para que esté envuelta en un elemento en línea (ej. <span>).
    tagfilter boolean true Habilita el GitHub Tag Filter para mejorar la seguridad eliminando etiquetas HTML peligrosas.
    preserveFrontmatter boolean false Si es true, no se eliminará el frontmatter al principio de la cadena Markdown.
    components Overrides {} Un mapa de etiquetas HTML a componentes personalizados (ej. { h1: MyHeading }).
    wrapper Component null Un componente personalizado para envolver el Markdown renderizado.
    renderMarkdown Function null Una función de renderizado personalizada para reemplazar completamente el compilador de Markdown predeterminado.
    Anidación
    HTML