f5xc-docs-tools

ปลั๊กอิน f5xc-docs-tools ตรวจสอบความถูกต้องของไฟล์เนื้อหา MDX สำหรับไปป์ไลน์เอกสาร f5-sales-demo โดยจะตรวจจับปัญหาทั่วไปที่ทำให้การ build ล้มเหลวก่อนที่จะถึง CI รวมถึงอักขระ JSX ที่ไม่ได้ครอบ, การ import ที่ไม่ถูกต้อง, การอ้างอิงรูปภาพที่เสีย และ frontmatter ที่ไม่สมบูรณ์

v1.1.2 ประสิทธิภาพการทำงาน

การติดตั้ง

/plugin install f5xc-docs-tools@f5-sales-demo-marketplace

ทักษะ

mdx-content-reviewer

ทักษะนี้จะเปิดใช้งานโดยอัตโนมัติเมื่อ Claude ตรวจพบว่าคุณกำลังทำงานกับไฟล์ MDX ในรีโพซิทอรีเนื้อหา f5-sales-demo โดยจะทำการตรวจสอบ 7 รายการ:

การตรวจสอบ Frontmatter

ตรวจสอบฟิลด์ที่จำเป็นเช่น title และ sidebar.order หน้า Splash ต้องมีฟิลด์ hero และ template: splash

ปัญหาไวยากรณ์ MDX

ตรวจจับอักขระ < ที่ไม่ได้ครอบ และ \{ \} วงเล็บปีกกาที่ไม่ได้ escape ซึ่งทำให้การแยกวิเคราะห์ MDX เสียหาย

การตรวจสอบ Import

ตรวจสอบ import เทียบกับรายการที่อนุญาตของคอมโพเนนต์ ในตัวของ Starlight และคอมโพเนนต์ธีม f5-sales-demo

แอตทริบิวต์คอมโพเนนต์

ตรวจสอบ props ที่จำเป็นสำหรับคอมโพเนนต์เช่น Screenshot, Aside, Code, LinkCard, Card และ Badge

การอ้างอิงรูปภาพ

ตรวจสอบว่ารูปภาพที่อ้างอิงมีอยู่ในไดเรกทอรี docs/images/

การตรวจสอบโครงสร้าง

ตรวจสอบว่า docs/index.mdx มีอยู่จริง และไดเรกทอรีรูปภาพ ไม่มีไฟล์ MDX ที่หลุดเข้ามา

Export และบล็อกโค้ด

ตรวจสอบว่าตัวแปรที่ใช้ใน props code ของคอมโพเนนต์ Code มี export ที่ตรงกัน

พฤติกรรมการกำหนดขอบเขต

ทักษะนี้กำหนดขอบเขตการตรวจสอบอย่างชาญฉลาด:

• หากมีการเปลี่ยนแปลงที่ยังไม่ได้ commit หรือ stage ในไฟล์ docs/**/*.mdx จะตรวจสอบเฉพาะไฟล์เหล่านั้น
• มิฉะนั้น จะตรวจสอบไฟล์ docs/**/*.mdx ทั้งหมด

รูปแบบผลลัพธ์

ผลการตรวจพบจะถูกจัดกลุ่มตามระดับความรุนแรง:

• ERROR — จะทำให้การ build ล้มเหลว; ต้องแก้ไขก่อน merge
• WARNING — ปัญหาที่น่าจะเกิดขึ้นซึ่งควรได้รับการแก้ไข
• INFO — ข้อเสนอแนะและแนวปฏิบัติที่ดี

ผลการตรวจพบแต่ละรายการจะรวมเส้นทางไฟล์ หมายเลขบรรทัด และคำอธิบายของปัญหา

คำสั่ง

/review-mdx

/f5xc-docs-tools:review-mdx [path-or-glob]

รันทักษะ mdx-content-reviewer ตามต้องการ

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
path-or-glob	ไม่	เส้นทางไฟล์หรือรูปแบบ glob เพื่อกำหนดขอบเขตการตรวจสอบ ค่าเริ่มต้นคือไฟล์ docs/**/*.mdx ทั้งหมด

ตัวอย่าง:

# ตรวจสอบไฟล์ MDX ทั้งหมดใน docs/
/f5xc-docs-tools:review-mdx

# ตรวจสอบไฟล์เฉพาะเจาะจง
/f5xc-docs-tools:review-mdx docs/getting-started.mdx

# ตรวจสอบไฟล์ที่ตรงกับรูปแบบ glob
/f5xc-docs-tools:review-mdx docs/guides/*.mdx

ผลลัพธ์: บรรทัดสรุปท้ายจะรายงานจำนวนไฟล์ทั้งหมดที่ตรวจสอบ และจำนวนผลการตรวจพบแยกตามระดับความรุนแรง

Import ที่อนุญาต

ปลั๊กอินตรวจสอบ import เทียบกับแหล่งเหล่านี้:

คอมโพเนนต์ในตัวของ Starlight (@astrojs/starlight/components):

Aside Badge Card CardGrid Code FileTree Icon LinkCard Steps TabItem Tabs

คอมโพเนนต์ธีม f5-sales-demo (@f5-sales-demo/docs-theme/components/):

Banner Icon LinkCard Screenshot

คำเตือน

คอมโพเนนต์ธีมใช้ default import จากไฟล์ .astro แต่ละไฟล์ การ import จาก node_modules โดยตรง, เส้นทางสัมพัทธ์ และ การเรียก require() จะถูกแจ้งเตือนเป็น warning

ข้อมูลอ้างอิงคอมโพเนนต์อย่างรวดเร็ว

คอมโพเนนต์	Props ที่จำเป็น	Props เสริม
Screenshot	alt + อย่างน้อยหนึ่งใน light หรือ dark	—
Aside	type	title
Code	code, lang	title, frame, mark, ins, del
LinkCard (ธีม)	title, href	description, icon
Card	title	icon
Badge	text	variant
Steps	—	—
Tabs / TabItem	TabItem: label	—
CardGrid	—	—
FileTree	—	—

ปัญหาที่พบบ่อยใน MDX

ปัญหาทั่วไปที่ปลั๊กอินตรวจจับ:

ปัญหา	สาเหตุ	วิธีแก้ไข
< ที่ไม่ได้ครอบ	MDX ตีความว่าเป็นแท็ก JSX	ใช้ <, inline code หรือเขียนใหม่
\{ \} ที่ไม่ได้ escape	MDX ถือว่าเป็น JSX expression	ใช้ inline code, escape ด้วย \ หรือใช้บล็อกโค้ด
วงเล็บปีกกาในชื่อไฟล์	Astro ไม่สามารถประมวลผลไฟล์ได้	อย่าใช้ \{ หรือ \} ในชื่อไฟล์ .mdx