كيفية إضافة صور رأس للمقالات في Gatsby Starter Blog مع دعم بطاقات تويتر

مقدمة: لماذا تحتاج صور الرأس وبطاقات تويتر في مدونة Gatsby؟

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

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

الهدف هنا هو تحقيق ثلاثة أمور أساسية:

• إضافة صورة رأس كبيرة داخل صفحة المقال.
• إظهار معاينة محسنة للرابط عبر بطاقة Summary Card with Large Image عند توفر صورة خاصة بالمقال.
• استخدام صورة افتراضية عندما لا يحتوي المقال على صورة مخصصة.

هذه النتيجة مفيدة جداً من ناحية السيو، لأنها تحسن العرض البصري للمحتوى، وتمنح محركات البحث ومنصات المشاركة بيانات وصفية أدق وأكثر اكتمالاً.

الأدوات التي يعتمد عليها الحل داخل Gatsby Starter Blog

الميزة الجيدة أن معظم الأدوات اللازمة متوفرة مسبقاً داخل بيئة Gatsby، ولا تحتاج إلى بنية مخصصة من الصفر. ستتعامل غالباً مع العناصر التالية:

• React Helmet لإضافة وسوم meta داخل رأس الصفحة.
• gatsby-source-filesystem لقراءة الصور والملفات من النظام المحلي.
• gatsby-image أو المكون المرتبط بالصور لعرض الصور بطريقة محسنة وسريعة.
• gatsby-plugin-sharp لمعالجة الصور وتغيير أبعادها بكفاءة.
• GraphQL لجلب بيانات الصور وخصائص المقالات من ملفات المحتوى.

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

الخطوات الرئيسية لإضافة صور المقالات ودعم بطاقات تويتر

1. تحديث بيانات الصفحة الوصفية داخل مكون SEO.
2. جلب الصورة الافتراضية للموقع باستخدام GraphQL.
3. جلب صورة مخصصة لكل مقال من ملف frontmatter.
4. عرض صورة الرأس داخل قالب المقال.
5. إضافة خصائص جديدة داخل ملف المقال بصيغة Markdown.

تحديث وسوم البيانات الوصفية داخل مكون SEO

الخطوة الأولى هي تجهيز وسوم meta التي تقرؤها تويتر وفيسبوك وواتساب وجوجل وغير ذلك من الأدوات الداعمة لـ Open Graph. في الغالب ستجد أن ملف src/components/seo.js يحتوي مسبقاً على جزء كبير من هذه الوسوم، مثل og:title وtwitter:description وtwitter:card.

لكن المطلوب هنا هو توسيع هذا المكون ليستقبل خاصيتين إضافيتين هما imageUrl وimageAlt. الأولى تمثل الرابط الكامل للصورة، والثانية تمثل النص البديل المستخدم عند وصف الصورة.

يُنصح هنا باستخدام رابط كامل Fully Qualified URL للصورة، لأن وسوم Open Graph لا تعمل بشكل موثوق مع المسارات النسبية فقط.

مثال على دالة مساعدة لبناء الرابط الكامل

// util.js
export const constructUrl = (baseUrl, path) =>
  (!baseUrl || !path) ? null : `${baseUrl}${path}`;

تعديل مكون SEO لإضافة الصورة

// src/components/seo.js
const SEO = ({ description, lang, meta, title, imageUrl, imageAlt }) => {
  const data = useStaticQuery(
    // GraphQL query
  );

  const defaultImageUrl = constructUrl(
    data.site.siteMetadata.siteUrl,
    data.ogImageDefault?.childImageSharp?.fixed?.src
  );

  const ogImageUrl = imageUrl || defaultImageUrl;

  return (
    <Helmet
      htmlAttributes={{ lang }}
      title={title}
      meta={[
        { property: `og:image`, content: ogImageUrl },
        {
          property: `twitter:card`,
          content: imageUrl ? `summary_large_image` : `summary`,
        },
        {
          property: `twitter:image:alt`,
          content: imageAlt || `شعار الموقع`,
        },
      ]}
    />
  );
};

ملاحظات مهمة حول وسوم Open Graph وTwitter Cards

• يمكن لتويتر الاعتماد على الوسم og:image دون الحاجة دائماً إلى إضافة twitter:image بشكل منفصل.
• وسوم Open Graph تستخدم الخاصية property، بينما بعض الوسوم الأخرى مثل description تعتمد على name.
• اختيار summary_large_image مناسب عندما تكون للمقال صورة كبيرة وواضحة.
• إذا لم تكن هناك صورة للمقال، فمن الأفضل استخدام بطاقة summary مع صورة افتراضية بسيطة.

جلب الصورة الافتراضية للموقع عبر GraphQL

بعد تجهيز الوسوم، تحتاج إلى توفير صورة افتراضية تستخدم عند غياب صورة خاصة بالمقال. هنا يأتي دور useStaticQuery داخل ملف SEO.

// src/components/seo.js
const data = useStaticQuery(graphql`
  query {
    site {
      siteMetadata {
        title
        description
        social {
          twitter
        }
        siteUrl
      }
    }
    ogImageDefault: file(relativePath: { eq: "icon.png" }) {
      childImageSharp {
        fixed(height: 260, width: 260) {
          src
        }
      }
    }
  }
`);

في هذا الاستعلام، الاسم ogImageDefault هو مجرد اسم مستعار alias للعقدة file. ويتم البحث عن ملف اسمه icon.png ضمن المسارات التي تم تسجيلها مسبقاً عبر الإضافة gatsby-source-filesystem.

كيف يعرف Gatsby مكان الصورة؟

يعتمد ذلك على إعدادات ملف gatsby-config.js، حيث يتم تعريف جذور المحتوى مثل مجلد المقالات ومجلد الأصول الثابتة.

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/content/blog`,
        name: `blog`,
      },
    },
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        path: `${__dirname}/content/assets`,
        name: `assets`,
      },
    },
  ],
};

هذا يعني أن الملف icon.png يمكن العثور عليه داخل المسار ./content/assets/icon.png، لأن مجلد assets تم تعريفه كمصدر محتوى معروف لدى Gatsby.

فهم childImageSharp وfixed

العقدة childImageSharp تشير إلى أن الملف الصوري تمت معالجته عبر مكتبة Sharp. أما الحقل fixed فيستخدم عندما تريد الحصول على صورة بأبعاد ثابتة، مثل 260x260. وفي هذا السيناريو نحتاج فقط إلى الخاصية src لاستخدامها داخل الوسوم الوصفية.

جلب صورة مخصصة لكل مقال من خلال frontmatter

بعد إعداد الصورة الافتراضية، تأتي الخطوة الأهم وهي إتاحة صورة مختلفة لكل مقال. لتحقيق ذلك يجب تعديل قالب المقال الموجود غالباً في الملف src/templates/blog-post.js، بحيث يمرر خصائص الصورة إلى مكون SEO.

// src/templates/blog-post.js
<SEO
  title={data.markdownRemark.frontmatter.title}
  description={
    data.markdownRemark.frontmatter.description ||
    data.markdownRemark.excerpt
  }
  imageUrl={constructUrl(
    data.site.siteMetadata.siteUrl,
    data.markdownRemark.frontmatter.image?.childImageSharp?.fixed?.src
  )}
  imageAlt={data.markdownRemark.frontmatter.imageAlt}
/>

هنا يتم بناء الرابط الكامل للصورة عبر الدالة constructUrl، بينما يتم أخذ النص البديل من الحقل imageAlt داخل frontmatter.

تحديث استعلام GraphQL داخل قالب المقال

// src/templates/blog-post.js
export const pageQuery = graphql`
  query BlogPostBySlug($slug: String!) {
    site {
      siteMetadata {
        title
        siteUrl
      }
    }
    markdownRemark(fields: { slug: { eq: $slug } }) {
      id
      excerpt(pruneLength: 160)
      html
      frontmatter {
        title
        date(formatString: "MMMM DD, YYYY")
        description
        image {
          childImageSharp {
            fixed(height: 600, width: 1200) {
              src
            }
            fluid(maxWidth: 700, maxHeight: 500) {
              ...GatsbyImageSharpFluid
            }
          }
        }
        imageAlt
        imageTitleHtml
      }
    }
  }
`;

في هذا الاستعلام، الحقل image يجب أن يطابق الاسم المستخدم داخل frontmatter في ملف المقال. وقيمة هذا الحقل يجب أن تكون مساراً نسبياً للصورة انطلاقاً من مكان ملف المقال نفسه.

كما تم استخدام نوعين من البيانات الصورية:

• fixed لاستخراج رابط صورة مناسب لوسوم المعاينة الاجتماعية.
• fluid لعرض الصورة داخل الصفحة بشكل متجاوب مع أحجام الشاشات.

من الأفضل أن تكون أبعاد الصورة الفعلية مساوية أو أكبر من القيم المحددة في الاستعلام، خاصة إذا كنت تستهدف بطاقة Summary Card with Large Image.

إضافة صورة الرأس داخل قالب المقال

بعد وصول بيانات الصورة إلى القالب، يمكنك عرضها أعلى المقال باستخدام مكون الصور في Gatsby، مع إضافة وصف أو حقوق الصورة أسفلها.

// src/templates/blog-post.js
import Image from "gatsby-image";

{data.markdownRemark.frontmatter.image?.childImageSharp?.fluid && (
  <>
    <Image
      fluid={data.markdownRemark.frontmatter.image.childImageSharp.fluid}
      alt={data.markdownRemark.frontmatter.imageAlt}
    />
    <div
      style={{
        textAlign: "center",
        fontSize: "14px",
        lineHeight: "28px",
      }}
      dangerouslySetInnerHTML={{
        __html: data.markdownRemark.frontmatter.imageTitleHtml,
      }}
    />
    <br />
    <br />
  </>
)}

التحقق الشرطي هنا مهم جداً، لأنه يمنع حدوث أخطاء عند عدم وجود صورة أو نص بديل داخل بيانات المقال. ولهذا السبب تم استخدام optional chaining في أكثر من موضع.

لماذا يُعد هذا النهج مهماً لتحسين الأداء وتجربة المستخدم؟

• يعرض الصور بشكل متجاوب على الهواتف وأجهزة سطح المكتب.
• يساعد على تحسين سرعة التحميل بفضل أدوات Gatsby المخصصة للصور.
• يمنح المقال مظهراً بصرياً أكثر احترافية.
• يزيد فرص ظهور المعاينات بشكل صحيح عند مشاركة الروابط.

إضافة خصائص الصورة إلى ملف المقال بصيغة Markdown

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

---
title: "Working with Heterogeneous Item Collections in the DynamoDB Enhanced Client for Java"
date: "2020-12-07T01:51:34.815Z"
description: "Working with heterogeneous item collections with the Java SDKs can be tricky. Here we see how to handle them with the AWS SDK v2 for Java's Enhanced Client."
image: "./kevin-mueller-gGUiw8GNIFE-unsplash.jpg"
imageAlt: "قطرات ماء على خلفية سوداء"
imageTitleHtml: '<span>Photo by <a href="https://unsplash.com/@kevinmueller?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Kevin Mueller</a> on <a href="https://unsplash.com/?utm_source=unsplash&utm_medium=referral&utm_content=creditCopyText">Unsplash</a></span>'
---

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

أفضل الممارسات لضمان قبول أفضل في AdSense وتحسين السيو

• استخدم صوراً أصلية أو مرخصة قانونياً مع توضيح المصدر عند الحاجة.
• اكتب نصاً بديلاً واضحاً داخل imageAlt يصف الصورة بدقة.
• احرص على أن تكون الصور مرتبطة بمحتوى المقال وليست مجرد عناصر تجميلية.
• لا تعتمد على الصور فقط، بل قدّم شرحاً تقنياً فعلياً يجيب عن أسئلة القارئ.
• اختبر معاينة الرابط باستخدام أدوات مثل Twitter Card Validator قبل النشر النهائي.
• راجع الصفحة عبر أداة Lighthouse لاكتشاف مشاكل السيو الأساسية.

ملاحظات عملية بعد النشر

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

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

الخلاصة التقنية

إضافة صور رأس للمقالات في Gatsby Starter Blog ليست مجرد تحسين بصري، بل خطوة استراتيجية تجمع بين تحسين تجربة المستخدم، ورفع جودة المعاينات الاجتماعية، وتعزيز إشارات السيو التقنية. عند ربط frontmatter مع GraphQL ومكون SEO، تحصل على بنية مرنة وقابلة للتوسع، تسمح لكل مقال بأن يملك هويته البصرية الخاصة دون التخلي عن صورة افتراضية احتياطية. تقنياً، هذا النهج يُعد من أفضل الطرق لبناء مدونة حديثة جاهزة للمشاركة والأرشفة والفهرسة بشكل احترافي.