وثائق استخدام الصفحات المسطحة

Platpages هو نظام إدارة صفحات ثابت بسيط وقوي يدعم كتابة المحتوى بتنسيق Markdown ، ويقوم تلقائيًا بإنشاء الدلائل ، ويوفر واجهة قراءة جمالية.

ميزات وظيفية

• يدعم تنسيق التخفيض لكتابة المحتوى
• إنشاء كتالوجات المقالات تلقائيًا
• رمز تسليط الضوء
• اقرأ تعليمات التقدم
• تصميم متجاوب ، دعم للجوال
• دعم مقالة التنقل (السابق/التالي)
• دعم مقالة البحث
• الدعم الدولي

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

1. تمكين التكوين

تمكين الصفحات المسطحة في ملف التكوين:

[flatpages] 
    # 是否启用flatpages 
    enable = true 
    # 支持配置多个flatpage目录 
    [[flatpages.dirs]] 
        nav_name = "帮助文档" 
        nav_path = "docs" 
        file_path = "statics/flatpages/docs" 
        # 每页显示的条目数，可选，默认为10 
        page_size = 20 
 
    # 可以继续添加更多目录配置... 

2. إنشاء مقال

قم بإنشاء ملف .md في دليل statics/flatpages ، واكتبه بالتنسيق التالي:

# 文章标题 
 
> 文章描述（会显示在列表页） 
 
正文内容... 
 
## 二级标题 
 
### 三级标题 
 
正文内容... 

3. وصف تنسيق التخفيض

تدعم الصفحات المسطحة بناء جملة التخفيض القياسي ، بما في ذلك:

• العنوان (H1-H4)
• قائمة (مرتبة وغير مرتبة)
• كتلة الكود (يدعم تمييز بناء الجملة)
• كتلة مرجعية
• وصلة
• صورة
• رمز مضمّن

مثال كتلة الكود:

def hello(): 
    print("Hello, World!") 

4. وظائف خاصة

نسخة رمز

سيتم إضافة زر النسخ تلقائيًا إلى الزاوية اليمنى العليا لجميع كتل التعليمات البرمجية لتسهيل المستخدمين لنسخ الرمز.

دليل التنقل

سيقوم النظام تلقائيًا بإنشاء دليل بناءً على عنوان المقالة (H2-H4) وعرضه على اليمين. دعم الدليل:

• تلقائيًا تسليط الضوء على موضع القراءة الحالي
• انقر للقفز
• تزامن التمرير

قراءة التقدم

سيتم عرض شريط التقدم في القراءة في الجزء العلوي من الصفحة ، والذي سيعرض بصريًا موضع القراءة.

مبدأ التنفيذ

1. نظام الملفات

تستخدم Platpages Jo's embed.FS لإدارة الملفات الثابتة:

//go:embed flatpages/* 
var Files embed.FS 

2. تسجيل التوجيه

يسجل النظام الطرق ذات الصلة من خلال وظيفة InitFlatpages عند بدء التشغيل:

• /fp/ - صفحة قائمة المقالات
• /fp/:slug - صفحة تفاصيل المقالة

3. تحليل تخفيض

استخدم حزمة gomarkdown/markdown لتحليل التمييز ، الدعم:

• commonextensions
• الرؤوس التلقائية
• HreftargetBlank

4. إدارة المقالات

سيتم تحميل جميع ملفات Markdown عند بدء التشغيل:

1. حل اسم الملف كـ URL Slug
2. استخراج عنوان المقالة (H1)
3. استخراج وصف المقالة (كتلة الاقتباس الأولى)
4. حساب وقت القراءة
5. سجل وقت التحديث

5. تنفيذ البحث

يتم تنفيذ وظيفة البحث في صفحات القائمة في JavaScript ، والتي تدعم البحث في الوقت الفعلي للعناوين والأوصاف.

6. الدعم الدولي

يدمج النظام دعم I18N ، ويمكن تمكين الدعم متعدد اللغات من خلال التكوين:

[i18n] 
enable = true 

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

1. تسمية الملف
   • استخدم اسم ملف ذي معنى ، سيتم استخدامه كجزء من عنوان URL
   • تجنب الشخصيات والمساحات الخاصة
   • ينصح الحروف الصغيرة والواصلة
2. منظمة المحتوى
   • يجب أن يكون لكل ملف عنوان H1
   • استخدم كتل الاقتباس لإضافة وصف المقالة
   • استخدم العناوين الثانوية والثالثة بشكل معقول لتنظيم المحتوى
   • التحكم في حجم ملف واحد ، يوصى بعدم تجاوز 1000 سطر.
3. معالجة الصور
   • يوصى بتخزين الصور في دليل statics/img
   • الصور المرجعية باستخدام المسارات النسبية
   • ضغط الصور لزيادة سرعة التحميل
4. عرض الكود
   • حدد لغة كتلة الكود للحصول على تمييز بناء الجملة الصحيح
   • أضف تعليقات إلى رمز مهم
   • تأكد من أن كتلة الكود بادئة بشكل صحيح

استكشاف الأخطاء وإصلاحها

1. الصفحة غير معروضة
   • تحقق مما إذا كانت flatpages.enable .
   • تأكد من أن ملف Markdown في الدليل الصحيح
2. الدليل لم يتم إنشاؤه
   • تحقق مما إذا كانت المقالة تحتوي على عنوان ثانوي أو ثلاثي
   • تأكد من أن العنوان صحيح (## أو ###)
3. استثناء نمط
   • تحقق مما إذا كان بناء جملة Markdown صحيحًا
   • تأكيد أن ترميز الملف هو UTF-8
4. بحث غير صالح
   • تحقق من وحدة التحكم في المتصفح لأخطاء JavaScript
   • تأكد من تحميل الصفحة JavaScript بشكل صحيح