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

    Markdown / Contenu Texte Riche

    Intlayer prend en charge le contenu texte riche défini à l'aide de la syntaxe Markdown. Cela vous permet de rédiger et de gérer facilement du contenu avec une mise en forme avancée, comme des blogs, des articles, et bien plus encore.

    Déclarer du Contenu Markdown

    Vous pouvez déclarer du contenu Markdown en utilisant la fonction md ou simplement comme une chaîne de caractères (si elle contient de la syntaxe Markdown).

    Depuis la version 8.10.0, vous pouvez déclarer du contenu Markdown directement dans des fichiers .content.md. Intlayer détectera et analysera automatiquement le contenu Markdown.

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: Mon contenulocale: en---# Mon contenuVoici un exemple de contenu markdown

    Le champ front-matter locale permet de définir la langue du contenu. Il est optionnel. S'il n'est pas fourni, Intlayer utilisera la langue par défaut, qui sert également de langue de secours si aucune traduction n'est disponible pour une langue spécifique.

    Exemple de structure de fichiers :

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

    Vous pouvez ajouter dans le front-matter n'importe quelle propriété définie dans la Définition du dictionnaire

    Rendu Markdown

    Intlayer propose deux manières indépendantes de rendre du Markdown :

    1. Via useIntlayer — Intlayer transforme automatiquement le nœud md dans le format natif du framework (JSX, VNode, chaîne HTML).

      • Le frontmatter est analysé et exposé sous .metadata. Vous pouvez remplacer le rendu à deux niveaux — globalement avec MarkdownProvider (ou l'équivalent du framework) et localement par nœud avec .use(). Les deux peuvent être combinés ; .use() est prioritaire sur MarkdownProvider, qui est lui-même prioritaire sur le rendu par défaut.

    2. Utilitaires d'aide — <MarkdownRenderer />, useMarkdownRenderer() et renderMarkdown() sont des outils indépendants qui n'acceptent que des chaînes Markdown brutes. Ils sont indépendants de useIntlayer et ne fonctionnent pas avec les nœuds décorés qu'il retourne.

    Le rendu Markdown prend en charge MDX — utilisez n'importe quel composant JSX/framework par son nom directement dans votre Markdown.

    1. Rendu Automatique (via useIntlayer)

    Les nœuds Markdown peuvent être rendus directement sous forme de 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} />, // Composant MDX    }}  >    <AppContent />  </MarkdownProvider>);
    Si MarkdownProvider n'est pas présent, Intlayer rendra le markdown en utilisant le parser par défaut de Markdown vers JSX.

    Vous pouvez également fournir des remplacements locaux pour des nœuds spécifiques en utilisant la méthode .use() :

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

    Vous pouvez récupérer le Markdown sous forme de chaîne de caractères :

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

    Et vous pouvez accéder aux métadonnées de votre markdown comme ceci :

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

    2. Utilitaires d'aide (Chaînes Markdown Uniquement)

    Ces utilitaires rendent des chaînes Markdown brutes et sont indépendants de useIntlayer. Utilisez-les lorsque vous devez afficher du Markdown provenant de sources autres que vos dictionnaires.

    Composant <MarkdownRenderer />

    Rend une chaîne Markdown avec des options spécifiques.

    tsx
    import { MarkdownRenderer } from "react-intlayer/markdown";<MarkdownRenderer forceBlock={true} tagfilter={true}>  {"# Mon Titre"}</MarkdownRenderer>

    Hook useMarkdownRenderer()

    Obtenez une fonction de rendu préconfigurée.

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

    Utilitaire renderMarkdown()

    Utilitaire autonome pour le rendu en dehors des composants.

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# Mon Titre", { forceBlock: true });

    Configuration Globale avec MarkdownProvider

    Le MarkdownProvider (ou son équivalent dans un framework) configure le pipeline de rendu Markdown pour toute votre application. Cela s'applique aussi bien au rendu automatique useIntlayer qu'aux utilitaires d'aide. Les options définies ici sont les options par défaut — .use() les remplace au niveau du nœud.

    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 est pris en charge — tout nom de composant utilisé dans votre Markdown (ex. <MyCustomJSXComponent />) est résolu par rapport à la correspondance dans components.

    Vous pouvez également utiliser votre propre rendu 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>);
    L'import dynamique de votre système de rendu Markdown est un bon moyen de réduire la taille du bundle de votre application.

    Suspense

    Le moteur de rendu Markdown d'Intlayer est chargé dynamiquement. Bien qu'optimisé, le chunk de l'analyseur sous-jacent fait environ 55 ko. Son chargement synchrone retarde le rendu initial de la page et dégrade le First Contentful Paint (FCP).

    Pour éviter de bloquer l'interface utilisateur, Intlayer s'intègre à l'API Suspense de React. Il récupère l'analyseur en arrière-plan et lève une Promise pendant le téléchargement.

    Enveloppez tout composant rendant le Markdown d'Intlayer dans une limite <Suspense>. Cela affiche un état de repli localisé pendant le téléchargement du chunk, permettant au reste de votre DOM de se rendre immédiatement.

    Avertissement : Si vous ne fournissez pas de limite <Suspense>, React suspendra au niveau racine ou bloquera le rendu de tout l'arbre des composants jusqu'à ce que le chunk de 55 ko soit complètement chargé.

    Dans Next.js App Router, vous pouvez utiliser soit React Suspense pour les composants clients, soit un fichier loading.tsx pour les composants serveurs.

    Composant Client :

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

    Composant Serveur avec 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;

    Rendu Côté Serveur (SSR) et Hydratation

    En comparaison avec d'autres parseurs Markdown tels que remark / rehype, Intlayer Markdown est sans dépendance et s'exécute aussi bien côté client que côté serveur.

    Cependant, Intlayer optimise l'analyse pour les frameworks de rendu côté serveur (SSR) (tels que Next.js App Router, React Router, Nuxt, SvelteKit, etc.).

    Au lieu d'envoyer des chaînes Markdown brutes au client et de les analyser dans le navigateur (ce qui entraîne une pénalité de performance), Intlayer vous permet de pré-analyser le Markdown en un arbre de syntaxe abstraite (AST) sur le serveur.

    Vous pouvez utiliser la fonction parseMarkdown du package Intlayer de votre framework côté serveur pour générer un AST sérialisable (objet ParsedMarkdown), et le transmettre directement au frontend. Tous les utilitaires de rendu Intlayer (comme <MarkdownRenderer>, useMarkdownRenderer, etc.) acceptent automatiquement cet objet AST et le rendent de manière transparente.

    Exemple dans une architecture Serveur/Client

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. Sur le serveur : Analyser le markdown en un AST sérialisableexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // Renvoyer l'AST au client sous forme de JSON  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. Sur le client : Rendre l'AST directement sans ré-analyseexport default function Page() {  const { content } = useLoaderData();  // Le renderer accepte soit une chaîne brute, soit l'AST analysé  return <MarkdownRenderer content={content} />;}

    Ce modèle garantit que la logique d'analyse Markdown est entièrement exécutée sur le serveur, ce qui réduit considérablement le temps d'exécution côté client et améliore la vitesse d'hydratation initiale.

    Référence des options

    Ces options peuvent être passées à MarkdownProvider, MarkdownRenderer, useMarkdownRenderer et renderMarkdown.

    Option Type Default Description
    forceBlock boolean false Force la sortie à être enveloppée dans un élément de niveau bloc (ex: <div>).
    forceInline boolean false Force la sortie à être enveloppée dans un élément en ligne (ex: <span>).
    tagfilter boolean true Active le GitHub Tag Filter pour une meilleure sécurité en supprimant les balises HTML dangereuses.
    preserveFrontmatter boolean false Si true, le frontmatter au début de la chaîne Markdown ne sera pas supprimé.
    components Overrides {} Une carte des balises HTML vers des composants personnalisés (ex: { h1: MyHeading }).
    wrapper Component null Un composant personnalisé pour envelopper le Markdown rendu.
    renderMarkdown Function null Une fonction de rendu personnalisée pour remplacer complètement le compilateur Markdown par défaut.
    Imbrication
    HTML