استخدام Shortcodes في Markdown

Shortcodes هي رموز قصيرة يمكنك تضمينها في ملفات Markdown الخاصة بك لإنشاء محتوى معقد بسهولة دون كتابة HTML أو كود مخصص.

ما هي Shortcodes؟

Shortcodes هي عناصر نائبة يتم استبدالها بمحتوى أكثر تعقيداً عند معالجة Markdown. إنها شائعة في مولدات المواقع الثابتة مثل Hugo و Jekyll.

الصيغة الأساسية

Hugo Shortcodes

{{< youtube dQw4w9WgXcQ >}}

{{< tweet 1234567890 >}}

{{< figure src="/images/photo.jpg" title="صورة جميلة" >}}

Jekyll Includes

{% include image.html url="/images/photo.jpg" caption="صورة جميلة" %}

{% include alert.html type="info" text="هذه رسالة معلوماتية" %}

Shortcodes المخصصة

إنشاء Shortcode في Hugo

<!-- layouts/shortcodes/alert.html -->
<div class="alert alert-{{ .Get "type" }}">
  {{ .Inner }}
</div>

الاستخدام:

{{< alert type="warning" >}}
تحذير هام!
{{< /alert >}}

Shortcodes متعددة الأسطر

{{< code language="python" >}}
def hello_world():
    print("مرحباً بالعالم!")
{{< /code >}}

أمثلة شائعة

تضمين الفيديو

{{< youtube "dQw4w9WgXcQ" >}}

{{< vimeo 123456789 >}}

معرض الصور

{{< gallery >}}
  {{< figure src="image1.jpg" >}}
  {{< figure src="image2.jpg" >}}
  {{< figure src="image3.jpg" >}}
{{< /gallery >}}

صناديق المعلومات

{{< note >}}
هذه ملاحظة هامة للقراء.
{{< /note >}}

{{< warning >}}
انتبه لهذه النقطة!
{{< /warning >}}

أفضل الممارسات

1. الاتساق: استخدام اصطلاحات تسمية واضحة
2. التوثيق: توثيق المعاملات المتاحة وأمثلة الاستخدام
3. معالجة الأخطاء: توفير معاملات افتراضية ورسائل خطأ واضحة
4. الأداء: تجنب العمليات المعقدة في Shortcodes
5. الوصولية: ضمان أن HTML الناتج متاح

الخلاصة

Shortcodes طريقة قوية لتوسيع وظائف Markdown دون تعقيد بنية المستند. إنها تعزز إعادة الاستخدام والاتساق وقابلية الصيانة في مشاريع المحتوى.

موارد إضافية

• دليل Hugo Shortcodes
• Jekyll Includes
• Docusaurus MDX