اللُّغَوِيّــ

شرح سكريبت إنشاء مجلدات السور للقرآن الكريم

نظرة عامة

هذا السكريبت مصمم لإنشاء هيكل مجلدات منظم لسور القرآن الكريم الـ114، مع توليد ملفات _index.md متوافقة مع نظام Hugo للمواقع الثابتة.

المتطلبات

import os

السكريبت يستخدم مكتبة os فقط - وهي مكتبة أساسية في Python لا تحتاج لتثبيت إضافي.

مكونات الكود

1. قائمة أسماء السور بالعربية

surah_names_arabic = [
    "الفاتحة", "البقرة", "آل عمران", ... , "الناس"
]

الوصف:

قائمة (List) تحتوي على أسماء السور الـ114 بالترتيب الصحيح حسب المصحف
تبدأ بسورة الفاتحة وتنتهي بسورة الناس
الأسماء مخزنة بصيغة UTF-8 لدعم اللغة العربية

2. الدالة الرئيسية `create_hugo_surah_folders`

def create_hugo_surah_folders(base_path="content/quran"):

المعاملات (Parameters):

base_path: المسار الأساسي لإنشاء المجلدات (الافتراضي: "content/quran")

خطوات عمل الدالة:

الخطوة 1: إنشاء المجلد الأساسي

if not os.path.exists(base_path):
    os.makedirs(base_path)
    print(f"Created base directory: {base_path}")

يتحقق من وجود المجلد الأساسي
إذا لم يكن موجودًا، يقوم بإنشائه
os.makedirs() ينشئ المجلد وأي مجلدات أب مطلوبة

الخطوة 2: حلقة إنشاء مجلدات السور

for i, surah_name in enumerate(surah_names_arabic, 1):

شرح enumerate(surah_names_arabic, 1):

enumerate تعطينا رقم الفهرس والقيمة معًا
المعامل 1 يجعل العد يبدأ من 1 بدلاً من 0
i = رقم السورة (1-114)
surah_name = اسم السورة بالعربية

الخطوة 3: تنسيق اسم المجلد

folder_name = f"{i:03d}"

التنسيق:

:03d يعني: رقم عشري بثلاثة خانات مع أصفار بادئة
النتائج:
- 001 للفاتحة
- 002 للبقرة
- 114 للناس

لماذا هذا التنسيق؟

يضمن ترتيبًا صحيحًا في نظام الملفات
يسهل البحث والتنقل
يحافظ على البنية المنظمة

الخطوة 4: إنشاء مجلد السورة

folder_path = os.path.join(base_path, folder_name)

if not os.path.exists(folder_path):
    os.makedirs(folder_path)

os.path.join() تدمج المسارات بشكل آمن
يتحقق من عدم وجود المجلد قبل الإنشاء

الخطوة 5: إنشاء ملف `_index.md`

index_file_path = os.path.join(folder_path, "_index.md")

index_content = f"""---
title: "سورة {surah_name}"
weight: {i}
---

# سورة {surah_name}

"""

مكونات ملف Hugo Front Matter:

YAML Front Matter (بين ---):
- title: عنوان السورة بالعربية
- weight: وزن الترتيب في Hugo (للتحكم في ترتيب العرض)
محتوى Markdown:
- عنوان رئيسي # باسم السورة

الخطوة 6: كتابة الملف

with open(index_file_path, "w", encoding="utf-8") as f:
    f.write(index_content)

ملاحظات مهمة:

encoding="utf-8" ضروري لحفظ النص العربي بشكل صحيح
استخدام with يضمن إغلاق الملف تلقائيًا
الوضع "w" = الكتابة (write)

3. نقطة التشغيل الرئيسية

if __name__ == "__main__":
    create_hugo_surah_folders("content/quran")

الشرح:

هذا الشرط يضمن تنفيذ الكود فقط عند تشغيل الملف مباشرة
لا يتم التنفيذ عند استيراد الملف كمكتبة (module)
يمكنك تغيير المسار "content/quran" حسب احتياجك

البنية الناتجة

بعد تشغيل السكريبت، ستحصل على هيكل مثل:

content/quran/
├── 001/
│   └── _index.md
├── 002/
│   └── _index.md
├── 003/
│   └── _index.md
...
├── 113/
│   └── _index.md
└── 114/
    └── _index.md

محتوى ملف `_index.md` النموذجي:

---
title: "سورة الفاتحة"
weight: 1
---

# سورة الفاتحة

كيفية الاستخدام

الطريقة الأساسية:

python surahs.py

سيتم إنشاء المجلدات في content/quran/

تخصيص المسار:

يمكنك تعديل السطر الأخير في الكود:

create_hugo_surah_folders("المسار/المخصص/الخاص/بك")

أو استيراد الدالة في ملف آخر:

from surahs import create_hugo_surah_folders

# إنشاء في مسار مختلف
create_hugo_surah_folders("content/ar/quran")

المخرجات (Output)

عند التشغيل، سترى رسائل مثل:

Created folder: 001
Created _index.md for Surah 001: سورة الفاتحة
Created folder: 002
Created _index.md for Surah 002: سورة البقرة
...
✅ Successfully created 114 surah folders with Hugo front matter!
📁 Location: /full/path/to/content/quran

الاستخدامات المقترحة

موقع قرآني بـ Hugo: إنشاء موقع ثابت لعرض القرآن الكريم
توثيق منظم: هيكل جاهز لإضافة محتوى لكل سورة
نظام إدارة محتوى: قاعدة للبناء عليها بإضافة الآيات والتفاسير

ملاحظات للتطوير

إضافات محتملة:

إضافة معلومات السورة:

index_content = f"""---
title: "سورة {surah_name}"
weight: {i}
verses_count: {verses_count[i-1]}
revelation_place: "{revelation_places[i-1]}"
---

إنشاء ملفات للآيات:

# إنشاء ملف لكل آية داخل مجلد السورة
for verse_num in range(1, verse_count + 1):
    verse_file = f"verse-{verse_num:03d}.md"

دعم لغات متعددة:

# إنشاء ملفات بلغات مختلفة
languages = ["ar", "en", "fr"]
for lang in languages:
    create_hugo_surah_folders(f"content/{lang}/quran")

الخلاصة

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

الكود كاملاً


import os

# Surah names in Arabic (according to Mushaf arrangement)
surah_names_arabic = [
    "ٱلْفَاتِحَةِ", "ٱلْبَقَرَةِ", "آلِ عِمْرَانَ", "ٱلنِّسَاءِ", "ٱلْمَائِدَةِ", "ٱلْأَنْعَامِ", 
    "ٱلْأَعْرَافِ", "ٱلْأَنْفَالِ", "ٱلتَّوْبَةِ", "يُونُسَ", "هُودٍ", "يُوسُفَ", 
    "ٱلرَّعْدِ", "إِبْرَاهِيمَ", "ٱلْحِجْرِ", "ٱلنَّحْلِ", "ٱلْإِسْرَاءِ", "ٱلْكَهْفِ", 
    "مَرْيَمَ", "طه", "ٱلْأَنْبِيَاءِ", "ٱلْحَجِّ", "ٱلْمُؤْمِنُونَ", "ٱلنُّورِ", 
    "ٱلْفُرْقَانِ", "ٱلشُّعَرَاءِ", "ٱلنَّمْلِ", "ٱلْقَصَصِ", "ٱلْعَنْكَبُوتِ", 
    "ٱلرُّومِ", "لُقْمَانَ", "ٱلسَّجْدَةِ", "ٱلْأَحْزَابِ", "سَبَإٍ", "فَاطِرٍ", 
    "يس", "ٱلصَّافَّاتِ", "ص", "ٱلزُّمَرِ", "غَافِرٍ", "فُصِّلَتْ", "ٱلشُّورَىٰ", 
    "ٱلزُّخْرُفِ", "ٱلدُّخَانِ", "ٱلْجَاثِيَةِ", "ٱلْأَحْقَافِ", "مُحَمَّدٍ", 
    "ٱلْفَتْحِ", "ٱلْحُجُرَاتِ", "ق", "ٱلذَّارِيَاتِ", "ٱلطُّورِ", "ٱلنَّجْمِ", 
    "ٱلْقَمَرِ", "ٱلرَّحْمَٰنِ", "ٱلْوَاقِعَةِ", "ٱلْحَدِيدِ", "ٱلْمُجَادِلَةِ", 
    "ٱلْحَشْرِ", "ٱلْمُمْتَحَنَةِ", "ٱلصَّفِّ", "ٱلْجُمُعَةِ", "ٱلْمُنَافِقُونَ", 
    "ٱلتَّغَابُنِ", "ٱلطَّلَاقِ", "ٱلتَّحْرِيمِ", "ٱلْمُلْكِ", "ٱلْقَلَمِ", 
    "ٱلْحَاقَّةِ", "ٱلْمَعَارِجِ", "نُوحٍ", "ٱلْجِنِّ", "ٱلْمُزَّمِّلِ", 
    "ٱلْمُدَّثِّرِ", "ٱلْقِيَامَةِ", "ٱلْإِنْسَانِ", "ٱلْمُرْسَلَاتِ", "ٱلنَّبَإِ", 
    "ٱلنَّازِعَاتِ", "عَبَسَ", "ٱلتَّكْوِيرِ", "ٱلِٱنْفِطَارِ", "ٱلْمُطَفِّفِينَ", 
    "ٱلِٱنْشِقَاقِ", "ٱلْبُرُوجِ", "ٱلطَّارِقِ", "ٱلْأَعْلَىٰ", "ٱلْغَاشِيَةِ", 
    "ٱلْفَجْرِ", "ٱلْبَلَدِ", "ٱلشَّمْسِ", "ٱللَّيْلِ", "ٱلضُّحَىٰ", "ٱلشَّرْحِ", 
    "ٱلتِّينِ", "ٱلْعَلَقِ", "ٱلْقَدْرِ", "ٱلْبَيِّنَةِ", "ٱلزَّلْزَلَةِ", 
    "ٱلْعَادِيَاتِ", "ٱلْقَارِعَةِ", "ٱلتَّكَاثُرِ", "ٱلْعَصْرِ", "ٱلْهُمَزَةِ", 
    "ٱلْفِيلِ", "قُرَيْشٍ", "ٱلْمَاعُونِ", "ٱلْكَوْثَرِ", "ٱلْكَافِرُونَ", 
    "ٱلنَّصْرِ", "ٱلْمَسَدِ", "ٱلْإِخْلَاصِ", "ٱلْفَلَقِ", "ٱلنَّاسِ"
]

def create_hugo_surah_folders(base_path="content/quran"):
    """
    Create folders for each surah with Hugo-compatible _index.md
    """
    
    # Create base directory
    if not os.path.exists(base_path):
        os.makedirs(base_path)
        print(f"Created base directory: {base_path}")
    
    # Create folders and _index.md files for each surah
    for i, surah_name in enumerate(surah_names_arabic, 1):
        # Format folder name with leading zeros (001, 002, etc.) - cleaner without name in folder
        folder_name = f"{i:03d}"
        folder_path = os.path.join(base_path, folder_name)
        
        # Create folder
        if not os.path.exists(folder_path):
            os.makedirs(folder_path)
            print(f"Created folder: {folder_name}")
        
        # Create _index.md file
        index_file_path = os.path.join(folder_path, "_index.md")
        
        # Hugo front matter with title and weight
        index_content = f"""---
title: "سورة {surah_name}"
weight: {i}
---

# سورة {surah_name}

"""
        
        # Write to _index.md
        with open(index_file_path, "w", encoding="utf-8") as f:
            f.write(index_content)
        
        print(f"Created _index.md for Surah {i:03d}: سورة {surah_name}")
    
    print(f"\n✅ Successfully created {len(surah_names_arabic)} surah folders with Hugo front matter!")
    print(f"📁 Location: {os.path.abspath(base_path)}")
    print("\n📘 Folder structure:")
    print("   001/")
    print("     └── _index.md")
    print("   002/")
    print("     └── _index.md")
    print("   ...")
    print("   114/")
    print("     └── _index.md")

if __name__ == "__main__":
    # You can change the path to match your Hugo content directory
    create_hugo_surah_folders(".")

تم بحمد الله 🌙