مجموعات المحتوى في Astro: الارتقاء بموقعك الإلكتروني بإدارة محتوى آمنة من ناحية النوع

Astro، مولد المواقع الثابتة الشهير، يقدم ميزة قوية تسمى مجموعات المحتوى. يوفر هذا النظام طريقة منظمة وآمنة من ناحية النوع لإدارة محتوى موقع الويب الخاص بك، مما يضمن الاتساق ويقلل الأخطاء ويحسن تجربة التطوير الشاملة. سواء كنت تقوم ببناء مدونة شخصية أو موقع توثيق أو منصة تجارة إلكترونية معقدة، يمكن لمجموعات المحتوى تبسيط سير عملك بشكل كبير.

ما هي مجموعات المحتوى في Astro؟

مجموعات المحتوى هي دليل مخصص داخل مشروع Astro الخاص بك حيث تقوم بتنظيم ملفات المحتوى الخاصة بك (عادةً Markdown أو MDX). يتم تعريف كل مجموعة بواسطة مخطط، والذي يحدد البنية وأنواع البيانات المتوقعة للواجهة الأمامية للمحتوى الخاص بك (البيانات الوصفية في بداية كل ملف). يضمن هذا المخطط أن يلتزم كل المحتوى داخل المجموعة بتنسيق متسق، مما يمنع التناقضات والأخطاء التي يمكن أن تنشأ من إدخال البيانات يدويًا.

فكر في الأمر على أنه قاعدة بيانات، ولكن لملفات المحتوى الخاصة بك. بدلاً من تخزين المحتوى في خادم قاعدة بيانات، يتم تخزينه في ملفات نصية عادية، مما يوفر مزايا التحكم في الإصدار ويسمح لك بالحفاظ على المحتوى الخاص بك قريبًا من التعليمات البرمجية. ومع ذلك، على عكس مجرد وجود مجلد لملفات Markdown، تفرض مجموعات المحتوى هيكلًا وأمانًا من النوع عبر المخطط.

لماذا تستخدم مجموعات المحتوى؟

• أمان النوع: يضمن تكامل TypeScript فحص نوع بيانات المحتوى الخاص بك أثناء التطوير، والتقاط الأخطاء مبكرًا ومنع مشكلات وقت التشغيل. هذا مفيد بشكل خاص في المشاريع الأكبر التي تضم العديد من المساهمين.
• التحقق من صحة المخطط: يتحقق المخطط المحدد من الواجهة الأمامية لكل ملف محتوى، مما يضمن وجود جميع الحقول المطلوبة وأن تكون من نوع البيانات الصحيح.
• تحسين اتساق المحتوى: من خلال فرض هيكل متسق، تساعد مجموعات المحتوى في الحفاظ على مظهر وملمس موحدين عبر موقع الويب الخاص بك.
• تجربة مطور محسنة: توفر واجهة برمجة التطبيقات الآمنة من النوع إكمالًا تلقائيًا ممتازًا واكتشاف الأخطاء في بيئة التطوير المتكاملة الخاصة بك، مما يجعل إدارة المحتوى أسهل وأكثر كفاءة.
• تبسيط الوصول إلى البيانات: يوفر Astro واجهة برمجة تطبيقات مريحة للاستعلام عن المحتوى والوصول إليه من مجموعاتك، مما يبسط استرجاع البيانات في مكوناتك.
• تنظيم المحتوى: توفر المجموعات هيكلًا واضحًا ومنطقيًا لتنظيم المحتوى الخاص بك، مما يسهل العثور عليه وإدارته. على سبيل المثال، قد يكون لموقع التوثيق مجموعات لـ "الأدلة" و "مرجع واجهة برمجة التطبيقات" و "سجل التغييرات".

البدء في استخدام مجموعات المحتوى

إليك دليل تفصيلي لتطبيق مجموعات المحتوى في مشروع Astro الخاص بك:

1. تمكين مجموعات المحتوى

أولاً، قم بتمكين تكامل @astrojs/content في ملف astro.config.mjs (أو ملف astro.config.js) الخاص بك:

            // astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { contentIntegration } from '@astrojs/content'

export default defineConfig({
  integrations: [
    mdx(),
    contentIntegration()
  ],
});

            

              
                Copy
              
            
          

2. إنشاء دليل مجموعة المحتوى

أنشئ دليلًا باسم src/content/[collection-name] حيث [collection-name] هو اسم مجموعتك (على سبيل المثال، src/content/blog). سيتعرف Astro تلقائيًا على هذا الدليل كمجموعة محتوى.

على سبيل المثال، لإنشاء مجموعة "مدونة"، يجب أن يبدو هيكل مشروعك هكذا:

  src/
    content/
      blog/
        my-first-post.md
        my-second-post.md
        ...
    pages/
    ...

3. تحديد مخطط المجموعة

أنشئ ملف src/content/config.ts (أو src/content/config.js) لتحديد المخطط لمجموعتك. يصدر هذا الملف كائن config الذي يحدد المخطط لكل مجموعة.

إليك مثال على مخطط لمجموعة "مدونة":

            // src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z
      .string()
      .or(z.date())
      .transform((val) => new Date(val)),
    updatedDate: z
      .string()
      .optional()
      .transform((str) => (str ? new Date(str) : undefined)),
    heroImage: z.string().optional(),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = {
  blog,
};

            

              
                Copy
              
            
          

شرح:

• defineCollection: تستخدم هذه الدالة لتعريف مجموعة محتوى.
• schema: تحدد هذه الخاصية المخطط الخاص بالواجهة الأمامية للمجموعة.
• z.object: هذا يحدد المخطط ككائن JavaScript. نحن نستخدم Zod للتحقق من صحة المخطط، وهي مكتبة شائعة لإعلان المخطط والتحقق من صحته أولاً في TypeScript.
• z.string(), z.date(), z.array(): هذه هي أنواع مخطط Zod، التي تحدد أنواع البيانات المتوقعة لكل حقل.
• z.optional(): يجعل الحقل اختياريًا.
• transform: يستخدم لتحويل بيانات الواجهة الأمامية. في هذه الحالة، نضمن أن تكون pubDate و updatedDate كائنات Date.

4. إنشاء ملفات المحتوى

أنشئ ملفات Markdown أو MDX داخل دليل مجموعتك (على سبيل المثال، src/content/blog/my-first-post.md). يجب أن يتضمن كل ملف واجهة أمامية تتوافق مع المخطط الذي حددته.

إليك مثال على ملف Markdown مع واجهة أمامية:

            ---
title: My First Blog Post
description: This is a short description of my first blog post.
pubDate: 2023-10-27
heroImage: /images/my-first-post.jpg
tags:
  - astro
  - blog
  - javascript
---

# My First Blog Post

This is the content of my first blog post.

            

              
                Copy
              
            
          

5. الوصول إلى المحتوى في مكوناتك

استخدم الدالة getCollection() من astro:content لاسترداد المحتوى من مجموعاتك في مكونات Astro الخاصة بك. تُرجع هذه الدالة صفيفًا من الإدخالات، يمثل كل منها ملف محتوى.

            // src/pages/blog.astro
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');

<ul>
  {posts.map((post) => (
    <li>
      <a href={`/blog/${post.slug}`}>{post.data.title}</a>
      <p>{post.data.description}</p>
    </li>
  ))}
</ul>

            

              
                Copy
              
            
          

شرح:

• getCollection('blog'): يسترد جميع الإدخالات من مجموعة "مدونة".
• post.slug: "slug" هو معرف فريد لكل ملف محتوى، يتم إنشاؤه تلقائيًا من اسم الملف (على سبيل المثال، 'my-first-post' لـ 'my-first-post.md').
• post.data: يحتوي على بيانات الواجهة الأمامية لكل إدخال، ويتم فحص النوع وفقًا للمخطط.

الميزات المتقدمة والتخصيص

توفر مجموعات المحتوى العديد من الميزات المتقدمة وخيارات التخصيص لتخصيص النظام ليناسب احتياجاتك الخاصة:

1. دعم MDX

تتكامل مجموعات المحتوى بسلاسة مع MDX، مما يسمح لك بتضمين مكونات JSX مباشرةً داخل محتوى Markdown الخاص بك. هذا مفيد لإنشاء محتوى تفاعلي وديناميكي.

لاستخدام MDX، قم بتثبيت تكامل @astrojs/mdx وقم بتهيئته في ملف astro.config.mjs الخاص بك (كما هو موضح في الخطوة 1). بعد ذلك، قم بإنشاء ملفات MDX (على سبيل المثال، my-post.mdx) واستخدم بناء جملة JSX داخل المحتوى الخاص بك.

            ---
title: My MDX Post
description: This post uses MDX.
---

# My MDX Post

<MyComponent prop1="value1" prop2={2} />

This is some regular Markdown content.

            

              
                Copy
              
            
          

2. أنواع المخططات المخصصة

يوفر Zod مجموعة واسعة من أنواع المخططات المضمنة، بما في ذلك string و number و boolean و date و array و object. يمكنك أيضًا تحديد أنواع مخططات مخصصة باستخدام طريقة .refine() في Zod لفرض قواعد تحقق أكثر تحديدًا.

على سبيل المثال، يمكنك التحقق من أن السلسلة هي عنوان URL صالح:

            // src/content/config.ts
import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  schema: z.object({
    title: z.string(),
    url: z.string().url(), // Validates that the string is a URL
  }),
});

export const collections = {
  blog,
};

            

              
                Copy
              
            
          

3. إنشاء Slug مخصص

بشكل افتراضي، يقوم Astro بإنشاء slug لكل ملف محتوى من اسم الملف. يمكنك تخصيص هذا السلوك عن طريق توفير خاصية slug في الواجهة الأمامية أو باستخدام خاصية entry.id لإنشاء slug مخصص بناءً على مسار الملف.

على سبيل المثال، لاستخدام مسار الملف لإنشاء slug:

            // src/pages/blog/[...slug].astro
import { getCollection, type CollectionEntry } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map((post) => ({
    params: { slug: post.slug }, // Use the default slug
    props: {
      post,
    },
  }));
}

type Props = {
  post: CollectionEntry<'blog'>;
};

const { post } = Astro.props as Props;

            

              
                Copy
              
            
          

4. تصفية المحتوى وفرزه

يمكنك استخدام طرق صفيف JavaScript (filter و sort وما إلى ذلك) لزيادة تحسين المحتوى المسترجع من مجموعاتك. على سبيل المثال، يمكنك تصفية المشاركات بناءً على علاماتها أو فرزها حسب تاريخ النشر.

            // src/pages/blog.astro
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');

const featuredPosts = posts.filter((post) => post.data.tags?.includes('featured'));
const sortedPosts = posts.sort((a, b) => new Date(b.data.pubDate).getTime() - new Date(a.data.pubDate).getTime());

            

              
                Copy
              
            
          

5. تدويل (i18n)

في حين أن مجموعات المحتوى لا توفر ميزات تدويل مباشرةً، يمكنك تنفيذ التدويل عن طريق إنشاء مجموعات محتوى منفصلة لكل لغة أو عن طريق استخدام حقل واجهة أمامية للإشارة إلى لغة كل ملف محتوى.

مثال باستخدام مجموعات منفصلة:

  src/
    content/
      blog-en/
        my-first-post.md
      blog-es/
        mi-primer-articulo.md

سيكون لديك بعد ذلك تعريفان للمجموعة: blog-en و blog-es، لكل منهما محتواه الخاص.

مثال باستخدام حقل lang في الواجهة الأمامية:

            ---
title: My First Blog Post
lang: en
---

# My First Blog Post

            

              
                Copy
              
            
          

بعد ذلك، ستقوم بتصفية المجموعة بناءً على حقل lang لاسترداد المحتوى الصحيح لكل لغة.

أفضل الممارسات لاستخدام مجموعات المحتوى

• خطط للمخطط الخاص بك بعناية: فكر في بنية وأنواع بيانات المحتوى الخاص بك قبل تحديد المخطط. سيجعل المخطط المصمم جيدًا إدارة المحتوى الخاص بك أسهل وأكثر كفاءة على المدى الطويل.
• استخدم أسماء حقول وصفية: اختر أسماء حقول واضحة وشرحة ذاتيًا. سيؤدي ذلك إلى تحسين إمكانية قراءة التعليمات البرمجية وقابليتها للصيانة.
• قدم أوصافًا واضحة لكل حقل: استخدم خاصية description في مخطط Zod لتقديم أوصاف مفيدة لكل حقل. سيساعد ذلك المطورين الآخرين (ونفسك في المستقبل) في فهم الغرض من كل حقل.
• فرض الحقول المطلوبة: استخدم طريقة required() في Zod للتأكد من وجود جميع الحقول المطلوبة في الواجهة الأمامية.
• استخدم الحقول الاختيارية باعتدال: استخدم الحقول الاختيارية فقط عندما تكون اختيارية حقًا. يساعد فرض الحقول المطلوبة في الحفاظ على الاتساق ومنع الأخطاء.
• وثق مجموعاتك: أنشئ وثائق لمجموعات المحتوى الخاصة بك، تشرح الغرض من كل مجموعة وهيكل المخطط وأي قواعد تحقق محددة.
• حافظ على تنظيم المحتوى الخاص بك: استخدم اصطلاح تسمية متسق لملفات المحتوى الخاصة بك وقم بتنظيمها في أدلة منطقية داخل مجموعاتك.
• اختبر مجموعاتك بدقة: اكتب اختبارات للتأكد من أن مجموعات المحتوى الخاصة بك تعمل بشكل صحيح وأن المخطط الخاص بك يتحقق من صحة الواجهة الأمامية كما هو متوقع.
• ضع في اعتبارك استخدام نظام إدارة محتوى للمؤلفين: بالنسبة لمواقع الويب التي تحتوي على محتوى كبير، فكر في إقران Astro بنظام إدارة محتوى بدون رأس. سيوفر هذا واجهة سهلة الاستخدام لمنشئي المحتوى الذين لا يحتاجون إلى التفاعل مع التعليمات البرمجية. تتضمن الأمثلة Contentful و Strapi و Sanity.

أمثلة على حالات الاستخدام: من المدونات الشخصية إلى التجارة الإلكترونية العالمية

إن تنوع مجموعات المحتوى في Astro يجعلها مناسبة لمجموعة واسعة من المشاريع:

• مدونة شخصية: إدارة منشورات المدونة مع حقول للعنوان وتاريخ النشر والمؤلف والمحتوى والعلامات. يسمح ذلك بتحديثات المحتوى السهلة وإنشاء قائمة المدونات وقائمة الفئات.
• موقع التوثيق: تنظيم صفحات التوثيق مع حقول للعنوان والإصدار والفئة والمحتوى. يتيح هيكل توثيق متسق وسهولة التنقل عبر الإصدارات المختلفة. ضع في اعتبارك مشروعًا كبيرًا مفتوح المصدر مثل Kubernetes، حيث يكون التوثيق أمرًا بالغ الأهمية.
• موقع تسويق: تحديد الصفحات مع حقول للعنوان والوصف والكلمات الرئيسية والمحتوى. تحسين المحتوى لتحسين محركات البحث والحفاظ على اتساق العلامة التجارية عبر جميع الصفحات.
• منصة التجارة الإلكترونية: فهرسة المنتجات مع حقول للاسم والسعر والوصف والصور والفئات. تنفيذ قائمة المنتجات الديناميكية وتسهيل تحديثات المنتج السهلة. للحصول على مثال للتجارة الإلكترونية العالمية، ضع في اعتبارك وجود مجموعات مختلفة بناءً على المنطقة لتلبية احتياجات الأسواق المحلية والمتطلبات القانونية. سيسمح ذلك بوجود حقول مختلفة مثل المعلومات الضريبية أو إخلاء المسؤولية التنظيمية بناءً على البلد.
• قاعدة المعرفة: تنظيم المقالات مع حقول للعنوان والموضوع والمؤلف والمحتوى. السماح للمستخدمين بالبحث بسهولة عن المقالات وتصفحها بناءً على الموضوع.

الخلاصة

توفر مجموعات المحتوى في Astro طريقة قوية وآمنة من ناحية النوع لإدارة محتوى موقع الويب الخاص بك. من خلال تحديد المخططات والتحقق من صحة الواجهة الأمامية وتوفير واجهة برمجة تطبيقات مريحة للوصول إلى البيانات، تساعد مجموعات المحتوى في ضمان اتساق المحتوى وتقليل الأخطاء وتحسين تجربة التطوير الشاملة. سواء كنت تقوم ببناء موقع ويب شخصي صغير أو تطبيق كبير ومعقد، يمكن لمجموعات المحتوى تبسيط سير عملك بشكل كبير ومساعدتك في إنشاء موقع ويب أكثر قوة وقابلية للصيانة.