Markdown Linter: ตรวจสอบและแก้ไขข้อผิดพลาดของ Markdown ก่อนเผยแพร่
เรียนรู้วิธีตรวจสอบและ style-check ไฟล์ Markdown ด้วย Markdown Linter ออนไลน์ฟรี จับ trailing whitespace, link เสีย และ header ผิดพลาดได้ทันทีขณะพิมพ์
Table of Contents
Markdown คือภาษามาตรฐานของเอกสารทางเทคนิคยุคใหม่ ตั้งแต่ไฟล์ README ในโปรเจกต์ open source ไปจนถึงบทความบล็อกและ documentation site ทั้งระบบ แต่เพราะ Markdown ออกแบบมาให้ "เขียนง่าย อ่านง่าย" หลายคนจึงมองข้ามรายละเอียดเล็ก ๆ อย่างช่องว่างเกินท้ายบรรทัด ลิงก์ที่ syntax เสีย หรือ header ที่ลืมเว้นวรรคหลังเครื่องหมาย # ปัญหาเหล่านี้ดูเหมือนเล็กน้อย แต่พอ render บน GitHub, GitLab หรือ static site generator คนละตัว ผลลัพธ์อาจเพี้ยนไปจากที่คาดไว้ หรือทำให้ git diff รกโดยไม่จำเป็น
Markdown Linter คือเครื่องมือออนไลน์ฟรีที่ช่วยตรวจสอบและ style check เนื้อหา Markdown ของคุณแบบเรียลไทม์ จับข้อผิดพลาดด้านการจัดรูปแบบที่พบบ่อยที่สุด พร้อมบอกเลขบรรทัดและระดับความรุนแรง (severity) ของแต่ละปัญหา เพื่อให้คุณแก้ได้ทันทีตั้งแต่ตอนพิมพ์ โดยไม่ต้องอัปโหลดไฟล์ไปที่ไหน ทุกอย่างทำงานในเบราว์เซอร์ทั้งหมด
ในบทความนี้ เราจะพาไปดูว่าทำไมการ lint Markdown ถึงสำคัญ ฟีเจอร์หลักของเครื่องมือมีอะไรบ้าง วิธีใช้งานทีละขั้นตอน และแนวทางปฏิบัติที่ดีเพื่อให้ไฟล์ Markdown ของคุณสะอาด สม่ำเสมอ และพร้อมเผยแพร่เสมอ
ทำไมต้องใช้ Markdown Linter?
การมี linter คอยตรวจ Markdown ก็เหมือนมี code review อัตโนมัติสำหรับเอกสารของคุณ เหตุผลหลัก ๆ ที่ควรใช้มีดังนี้
- จับปัญหาที่ตามองไม่เห็น — trailing whitespace หรือบรรทัดที่ยาวเกินไปเป็นสิ่งที่สังเกตได้ยากมากตอนพิมพ์ แต่ linter จะชี้ตำแหน่งให้ทันทีพร้อมเลขบรรทัด
- ป้องกันลิงก์เสียก่อน deploy — link syntax ที่ผิด เช่น มีช่องว่างนำหน้า URL ใน [text]( url) อาจทำให้บาง renderer ไม่สร้างลิงก์ให้เลย ซึ่งเท่ากับลิงก์ตาย (broken link) ที่ผู้อ่านกดไม่ได้
- รักษาความสม่ำเสมอของทีม — เมื่อทุกคนในทีมใช้ rule set เดียวกัน สไตล์การเขียนเอกสารจะเป็นมาตรฐานเดียวกัน ไม่ต้องเถียงกันในเรื่องเล็ก ๆ น้อย ๆ ตอน review
- ทำให้ git diff สะอาด — trailing whitespace และบรรทัดยาวเกินจำเป็นคือต้นเหตุของ diff noise ที่ทำให้การ review การเปลี่ยนแปลงเอกสารยากขึ้นโดยไม่จำเป็น
- ลดรอบการแก้งาน — แทนที่จะ push ขึ้น GitHub แล้วค่อยเห็นว่า heading render ผิด หรือลิงก์ไม่ทำงาน คุณสามารถจับ error เหล่านั้นได้ตั้งแต่ในขั้นตอนเขียน
- ไม่ต้องติดตั้งอะไรเลย — เครื่องมือนี้ทำงานบนเบราว์เซอร์ทั้งหมด ไม่ต้องลง CLI, ไม่ต้องตั้งค่า config file และไม่ต้องอัปโหลดไฟล์ เหมาะกับทั้งงานด่วนและงานประจำ
ฟีเจอร์หลัก
Markdown Linter มาพร้อม 4 lint rules ที่ครอบคลุมปัญหาการเขียน Markdown ที่พบบ่อยที่สุด แต่ละ rule มีระดับความรุนแรงต่างกัน ดังนี้
| Rule | Severity | เหตุผล |
|---|---|---|
| Trailing whitespace (ช่องว่างเกินท้ายบรรทัด) | Warning | ทำให้ diff รก และบาง renderer ตีความเป็น line break ต่างกัน |
| บรรทัดยาวเกิน 80 ตัวอักษร | Warning | อ่านยากใน terminal/diff และขัดต่อ convention ดั้งเดิมของเอกสารเทคนิค |
| Link syntax เสีย เช่น [text]( url) ที่มีช่องว่างนำหน้า URL | Error | หลาย renderer ไม่สร้างลิงก์ให้ ทำให้กลายเป็นลิงก์ตาย |
| Header ไม่มีช่องว่างหลัง # เช่น ##หัวข้อ | Error | ไม่เป็นไปตาม CommonMark spec บาง renderer ไม่ตีความเป็น heading |
รายละเอียดเพิ่มเติมของแต่ละส่วน:
- Live linting แบบเรียลไทม์ — เครื่องมือตรวจสอบขณะพิมพ์ทันที ไม่ต้องกดปุ่ม validate ทุกครั้งที่แก้ เนื้อหา ผลลัพธ์อัปเดตตามทุก keystroke
- รายงานผลชัดเจน — แต่ละ issue แสดงเลขบรรทัด ข้อความที่พบปัญหา และ severity (error หรือ warning) แยกกันใน panel ทำให้ง่ายต่อการไล่แก้ทีละจุด
- ทำงานในเบราว์เซอร์ 100% — มีปุ่ม Copy เพื่อนำผลลัพธ์ไปใช้ต่อ และปุ่ม Clear เพื่อล้างเนื้อหา ทั้งหมดทำงานฝั่ง client ไม่มีการอัปโหลดไฟล์ไปยังเซิร์ฟเวอร์ เนื้อหาของคุณไม่ออกจากเครื่อง
วิธีใช้งาน Markdown Linter
การใช้งานออกแบบให้ตรงไปตรงมาที่สุด ไม่ต้องสมัครสมาชิก ไม่ต้องล็อกอิน:
- เปิดเครื่องมือ — ไปที่ Markdown Linter บนเบราว์เซอร์ใดก็ได้ ทั้ง desktop และมือถือ
- วางหรือพิมพ์เนื้อหา Markdown — paste เนื้อหาจากไฟล์ .md ของคุณลงใน editor ด้านซ้าย หรือจะเริ่มพิมพ์ใหม่ตั้งแต่ต้นก็ได้
- ดูผล lint แบบเรียลไทม์ — panel ด้านข้างจะแสดงรายการ warnings และ errors พร้อมเลขบรรทัดทันทีที่เครื่องมือพบปัญหา
- ไล่แก้ทีละ issue — คลิกดูแต่ละรายการแล้วกลับไปแก้ที่บรรทัดนั้น error (เช่น ลิงก์เสีย, header ผิด) ควรแก้ให้หมด ส่วน warning (เช่น trailing whitespace, บรรทัดยาว) แนะนำให้แก้เช่นกันเพื่อให้ไฟล์สะอาด
- Copy ผลลัพธ์ไปใช้ — เมื่อทุกอย่างเรียบร้อย ใช้ปุ่ม Copy เพื่อนำเนื้อหาที่แก้แล้วกลับไปวางในไฟล์จริง หรือจะกด Clear เพื่อเริ่มตรวจเอกสารชิ้นใหม่ก็ได้
เข้าใจปัญหาที่พบบ่อยใน Markdown
รู้แค่ว่า "มี error" อย่างเดียวไม่พอ การเข้าใจว่าทำไมแต่ละ rule ถึงสำคัญจะช่วยให้คุณเขียน Markdown ได้ดีขึ้นในระยะยาว มาดูกันทีละ rule
1. Trailing whitespace (Warning)
ช่องว่างหรือ tab ที่อยู่ท้ายบรรทัดโดยไม่มีเนื้อหาตามหลัง เป็นปัญหาที่พบบ่อยที่สุดเพราะ editor ส่วนใหญ่ไม่แสดงมันให้เห็น ใน Markdown แบบดั้งเดิม ช่องว่าง 2 ตัวท้ายบรรทัดมีความหมายพิเศษคือบังคับขึ้นบรรทัดใหม่ (hard line break) ดังนั้น trailing whitespace ที่ไม่ได้ตั้งใจอาจเปลี่ยนโครงสร้างย่อหน้าโดยไม่รู้ตัว และที่สำคัญกว่านั้นคือมันทำให้ git diff แสดงการเปลี่ยนแปลงทั้งบรรทัดเพียงเพราะมีคนเผลอพิมพ์ช่องว่างเพิ่ม
บรรทัดนี้มีช่องว่างเกินท้ายบรรทัด บรรทัดถัดไปปกติ
วิธีแก้: ลบช่องว่างท้ายบรรทัดออกให้หมด ถ้าต้องการ line break จริง ๆ ให้ใช้บรรทัดว่างกั้นย่อหน้าแทน
2. บรรทัดยาวเกิน 80 ตัวอักษร (Warning)
convention ของเอกสารทางเทคนิคตั้งแต่ยุค Unix คือจำกัดความกว้างบรรทัดไว้ที่ 80 ตัวอักษร เพื่อให้ไฟล์อ่านได้ใน terminal ทุกขนาด และทำให้ git diff แสดงผลได้ครบโดยไม่ตัดบรรทัด แม้จอสมัยใหม่จะกว้างขึ้นมาก แต่บรรทัดที่ยาวเหยียดเป็นพรืดก็ยังอ่านยากอยู่ดี โดยเฉพาะตอน review ใน pull request
นี่คือตัวอย่างประโยคที่ยาวมาก ๆ จนเกินแปดสิบตัวอักษรซึ่งทำให้การอ่านใน terminal หรือหน้า diff ไม่สะดวกและต้องเลื่อนจอไปมา
วิธีแก้: ขึ้นบรรทัดใหม่เมื่อประโยคยาวเกินไป (Markdown จะรวมบรรทัดที่ติดกันเป็นย่อหน้าเดียวตอน render อยู่แล้ว) หรือตัดประโยคให้กระชับขึ้น
3. Link syntax เสีย (Error)
ลิงก์คือหัวใจของเอกสารบนเว็บ แต่ syntax ของลิงก์ Markdown ค่อนข้างจุกจิก รูปแบบที่ถูกต้องคือ [ข้อความ](url) โดยห้ามมีช่องว่างนำหน้า URL ในวงเล็บ เพราะหลาย renderer จะไม่ตีความว่าเป็นลิงก์ ผลคือผู้อ่านเห็นเป็นข้อความธรรมดาที่กดไม่ได้
ถูก: [Online Tools Forge](https://onlinetoolsforge.com) ผิด: [Online Tools Forge](https://onlinetoolsforge.com)
วิธีแก้: ลบช่องว่างระหว่าง ( กับ URL ออก และตรวจว่าวงเล็บเปิด-ปิดครบคู่กัน
4. Header ไม่มีช่องว่างหลัง # (Error)
ตาม CommonMark spec เครื่องหมาย # ต้องตามด้วยช่องว่างอย่างน้อย 1 ตัวจึงจะถือเป็น heading ถ้าเขียนติดกันเป็น ##หัวข้อ บาง renderer จะไม่ render เป็น heading ให้เลย ทำให้โครงสร้างเอกสาร (outline, table of contents, SEO heading hierarchy) เสียหาย
ถูก: ## หัวข้อหลัก ผิด: ##หัวข้อหลัก
วิธีแก้: เพิ่มช่องว่าง 1 ตัวหลังเครื่องหมาย # ทุกครั้ง และใช้จำนวน # ให้ตรงกับระดับ heading ที่ต้องการ
กรณีใช้งานจริง
ไฟล์ README สำหรับโปรเจกต์ open source
README คือหน้าด่านของทุกโปรเจกต์บน GitHub ถ้า heading render เพี้ยนหรือลิงก์ใน README กดไม่ได้ ความน่าเชื่อถือของโปรเจกต์ลดลงทันที การใช้ Markdown Linter ตรวจก่อน commit ช่วยให้ README ดูเป็นมืออาชีพ และลดโอกาสที่ contributor จะเจอเอกสารที่อ่านยาก
เว็บไซต์เอกสารทางเทคนิค
documentation site ที่สร้างจาก Markdown (เช่น Docusaurus, MkDocs, VitePress) มักมีไฟล์ .md จำนวนมาก ลิงก์เสียเพียงจุดเดียวอาจทำให้ผู้อ่านไปต่อไม่ได้ การ lint เป็นประจำช่วยจับ error ระดับ syntax ก่อนที่ build จะพาวนไปเจอปัญหาที่ใหญ่กว่า
ความสม่ำเสมอของสไตล์ในทีม
เมื่อทีมมีหลายคนเขียนเอกสารร่วมกัน สไตล์การเขียนมักไม่สม่ำเสมอ คนหนึ่งชอบบรรทัดสั้น อีกคนเขียนบรรทัดยาว การใช้ rule set เดียวกันผ่าน linter ช่วยให้เป็นมาตรฐานเดียวกันโดยอัตโนมัติ ลด friction ตอน review PR ด้าน documentation
เนื้อหาบล็อกและ CMS
บล็อกหลายระบบรับเนื้อหาเป็น Markdown โดยตรง trailing whitespace หรือ heading ที่ผิด syntax อาจทำให้ layout ของบทความเพี้ยนตอนเผยแพร่ การ lint ก่อน paste เข้า CMS ช่วยให้คุณเห็นหน้าตาจริงของบทความใกล้เคียงกับสิ่งที่ผู้อ่านจะเห็นมากที่สุด
แนวทางปฏิบัติที่ดีสำหรับ Markdown ที่สะอาด
- lint ก่อน commit ทุกครั้ง — ทำให้เป็นนิสัยเหมือนการรัน formatter ก่อน push โค้ด
- แก้ error ให้หมด อย่าปล่อย warning ค้าง — error อย่างลิงก์เสียหรือ header ผิดส่งผลต่อการ render โดยตรง ส่วน warning ก็ควรแก้เพื่อ diff ที่สะอาด
- ใช้บรรทัดว่างกั้นย่อหน้า แทนการเคาะช่องว่างท้ายบรรทัด — ชัดเจนกว่า พกพาข้าม renderer ได้ดีกว่า
- ตั้งเป้าบรรทัดละไม่เกิน 80 ตัวอักษร — ตัดบรรทัดเมื่อประโยคยาว และใช้ประโยชน์จากการที่ Markdown รวมบรรทัดเป็นย่อหน้าเดียวกัน
- ตรวจลิงก์ทุกครั้งหลังพิมพ์เสร็จ — ทั้ง syntax และ URL ปลายทาง ว่าไม่มีช่องว่างแปลกปลอมและวงเล็บครบคู่
- เว้นวรรคหลัง # เสมอ และใช้ระดับ heading ตามลำดับ — อย่าข้ามจาก ## ไป #### เพราะจะทำให้ outline ของเอกสารเสียโครงสร้าง
เริ่มตรวจสอบ Markdown ของคุณวันนี้
ไม่ต้องรอให้เอกสารเผยแพร่แล้วค่อยเจอปัญหา เปิด Markdown Linter แล้ววางเนื้อหา Markdown ของคุณลงไปตอนนี้เลย เครื่องมือจะบอกทันทีว่ามี trailing whitespace, บรรทัดยาว, ลิงก์เสีย หรือ header ผิดตรงบรรทัดไหนบ้าง แก้เสร็จในไม่กี่นาที เอกสารของ bạnก็จะสะอาด พร้อม push พร้อมเผยแพร่ และอ่านง่ายสำหรับทุกคนในทีม — ฟรี ไม่ต้องติดตั้ง ไม่ต้องสมัครสมาชิก
เครื่องมือที่เกี่ยวข้อง
ขอให้เขียน Markdown อย่างมีความสุข!