f5xc-docs-tools

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

v1.1.2 Productivity

การติดตั้ง

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

ทักษะ

mdx-content-reviewer

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

การตรวจสอบ 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 และ Code Block

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

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

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

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

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

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

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

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

คำสั่ง

/review-mdx

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

เรียกใช้ทักษะ mdx-content-reviewer ตามต้องการ

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

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
path-or-glob	ไม่	Path ของไฟล์หรือรูปแบบ 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 imports จากไฟล์ .astro แต่ละไฟล์ การ import โดยตรงจาก node_modules, relative paths และ การเรียก require() จะถูกแจ้งเตือนเป็น warning

เอกสารอ้างอิงส่วนประกอบอย่างย่อ

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

ข้อผิดพลาดทั่วไปใน MDX

ปัญหาที่พบบ่อยซึ่งปลั๊กอินตรวจจับ:

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