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/framework بالاسم مباشرة داخل 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 كيلوبايت. يؤدي تحميل هذا بشكل متزامن إلى تأخير عرض الصفحة الأولي ويقلل من سرعة عرض المحتوى الأول (FCP).

    لمنع حظر واجهة المستخدم، يتكامل Intlayer مع واجهة برمجة تطبيقات 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) والترطيب (Hydration)

    بالمقارنة مع محللات 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 إلى AST قابل للتسلسلexport 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