เอกสารการใช้งาน flatpages

FlatPages เป็นระบบการจัดการหน้าแบบคงที่ที่เรียบง่ายและทรงพลังซึ่งรองรับการเขียนเนื้อหาในรูปแบบ markdown สร้างไดเรกทอรีโดยอัตโนมัติและให้อินเทอร์เฟซการอ่านสุนทรียศาสตร์

คุณสมบัติการใช้งาน

• รองรับรูปแบบ Markdown เพื่อเขียนเนื้อหา
• สร้างแคตตาล็อกบทความโดยอัตโนมัติ
• การเน้นรหัส
• อ่านคำแนะนำความคืบหน้า
• การออกแบบที่ตอบสนองการสนับสนุนสำหรับมือถือ
• สนับสนุนบทความนำทาง (ก่อนหน้า/ถัดไป)
• สนับสนุนการค้นหาบทความ
• การสนับสนุนระหว่างประเทศ

วิธีใช้

1. เปิดใช้งานการกำหนดค่า

เปิดใช้งาน FlatPages ในไฟล์กำหนดค่า:

[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. คำอธิบายรูปแบบ Markdown

FlatPages รองรับไวยากรณ์ Markdown มาตรฐานรวมถึง:

• ชื่อเรื่อง (H1-H4)
• รายการ (สั่งซื้อและไม่ได้เรียงลำดับ)
• บล็อกรหัส (รองรับการไฮไลต์ไวยากรณ์)
• บล็อกอ้างอิง
• การเชื่อมโยง
• รูปภาพ
• รหัสอินไลน์

ตัวอย่างบล็อกโค้ด:

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

4. ฟังก์ชั่นพิเศษ

การคัดลอกรหัส

ปุ่มคัดลอกจะถูกเพิ่มโดยอัตโนมัติไปที่มุมขวาบนของบล็อกรหัสทั้งหมดเพื่ออำนวยความสะดวกให้ผู้ใช้คัดลอกรหัส

การนำทาง

ระบบจะสร้างไดเรกทอรีโดยอัตโนมัติตามชื่อของบทความ (H2-H4) และแสดงทางด้านขวา การสนับสนุนไดเรกทอรี:

• เน้นตำแหน่งการอ่านปัจจุบันโดยอัตโนมัติ
• คลิกเพื่อกระโดด
• การซิงโครไนซ์ม้วน

การอ่านความคืบหน้า

แถบความคืบหน้าการอ่านจะปรากฏขึ้นที่ด้านบนของหน้าซึ่งจะแสดงตำแหน่งการอ่านด้วยสายตา

หลักการดำเนินการ

1. ระบบไฟล์

FlatPages ใช้ GO's embed.FS เพื่อจัดการไฟล์คงที่:

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

2. การลงทะเบียนเส้นทาง

ระบบจะลงทะเบียนเส้นทางที่เกี่ยวข้องผ่านฟังก์ชั่น InitFlatpages เมื่อเริ่มต้น:

• /fp/ - หน้ารายการบทความ
• /fp/:slug - หน้ารายละเอียดบทความ

3. การวิเคราะห์ Markdown

ใช้แพ็คเกจ gomarkdown/markdown สำหรับการแยกวิเคราะห์ Markdown สนับสนุน:

• commonextensions
• AutoheadingIds
• HreftargetBlank

4. การจัดการบทความ

ไฟล์ Markdown ทั้งหมดจะถูกโหลดเมื่อเริ่มต้น:

1. แก้ไขชื่อไฟล์เป็น URL Slug
2. แยกชื่อบทความ (H1)
3. แยกคำอธิบายบทความ (บล็อกการอ้างอิงครั้งแรก)
4. คำนวณเวลาการอ่าน
5. บันทึกเวลาอัปเดต

5. การใช้งานการค้นหา

ฟังก์ชั่นการค้นหาของหน้ารายการถูกนำไปใช้ใน JavaScript ซึ่งรองรับการค้นหาชื่อและคำอธิบายแบบเรียลไทม์

6. การสนับสนุนระหว่างประเทศ

ระบบรวมการสนับสนุน I18N และการสนับสนุนหลายภาษาสามารถเปิดใช้งานได้ผ่านการกำหนดค่า:

[i18n] 
enable = true 

แนวทางปฏิบัติที่ดีที่สุด

1. การตั้งชื่อไฟล์
   • ใช้ชื่อไฟล์ที่มีความหมายซึ่งจะใช้เป็นส่วนหนึ่งของ URL
   • หลีกเลี่ยงอักขระและช่องว่างพิเศษ
   • แนะนำให้ใช้ตัวอักษรตัวพิมพ์เล็กและยัติภังค์
2. องค์กรเนื้อหา
   • แต่ละไฟล์ต้องมีชื่อ H1
   • ใช้บล็อกการอ้างอิงเพื่อเพิ่มคำอธิบายบทความ
   • ใช้ชื่อเรื่องระดับมัธยมศึกษาและระดับที่สามอย่างสมเหตุสมผลในการจัดระเบียบเนื้อหา
   • ควบคุมขนาดของไฟล์เดียวขอแนะนำให้ไม่เกิน 1,000 บรรทัด
3. การประมวลผลภาพ
   • รูปภาพจะแนะนำให้เก็บไว้ในไดเรกทอรี statics/img
   • ภาพอ้างอิงโดยใช้เส้นทางสัมพัทธ์
   • บีบอัดภาพเพื่อเพิ่มความเร็วในการโหลด
4. การแสดงรหัส
   • ระบุภาษาของบล็อกรหัสเพื่อรับการเน้นไวยากรณ์ที่ถูกต้อง
   • เพิ่มความคิดเห็นในรหัสสำคัญ
   • ตรวจสอบให้แน่ใจว่าบล็อกรหัสนั้นมีการเยื้องอย่างถูกต้อง

การแก้ไขปัญหา

1. หน้าไม่ปรากฏ
   • ตรวจสอบว่า flatpages.enable เป็นจริงในไฟล์การกำหนดค่า
   • ยืนยันว่าไฟล์ Markdown อยู่ในไดเรกทอรีที่ถูกต้อง
2. ไม่ได้สร้างไดเรกทอรี
   • ตรวจสอบว่าบทความมีชื่อรองหรือระดับตติยภูมิ
   • ยืนยันว่าชื่อถูกต้อง (## หรือ ###)
3. ข้อยกเว้นสไตล์
   • ตรวจสอบว่ามาร์คดาวน์ไวยากรณ์ถูกต้องหรือไม่
   • ยืนยันการเข้ารหัสไฟล์คือ UTF-8
4. การค้นหาที่ไม่ถูกต้อง
   • ตรวจสอบข้อผิดพลาดของเบราว์เซอร์สำหรับข้อผิดพลาด JavaScript
   • ยืนยันว่าหน้า JavaScript โหลดอย่างถูกต้อง