CommonMark: ข้อกำหนดอย่างเป็นทางการสำหรับ Markdown

CommonMark เป็นเวอร์ชันที่มีเหตุผลของไวยากรณ์ Markdown พร้อมข้อมูลจำเพาะซึ่งมีเป้าหมายเพื่อขจัดความกำกวมและความไม่สอดคล้องกันโดยรอบข้อกำหนด Markdown ดั้งเดิม มีข้อกำหนดมาตรฐานที่กำหนดรูปแบบทั่วไปของภาษาพร้อมกับชุดการทดสอบที่ครอบคลุมเพื่อตรวจสอบการใช้งาน Markdown กับข้อกำหนดนี้

GitHub ใช้ Markdown เป็นภาษามาร์กอัปสำหรับเนื้อหาของผู้ใช้

“CommonMark เป็นโครงการที่มีความทะเยอทะยานในการระบุรูปแบบ Markdown อย่างเป็นทางการที่ใช้โดยเว็บไซต์หลายแห่งบนอินเทอร์เน็ตในลักษณะที่สะท้อนถึงการใช้งานจริง [... ] ซึ่งช่วยให้ผู้คนสามารถใช้ Markdown ต่อไปได้เช่นเดียวกับที่พวกเขาเคยทำในขณะที่เสนอให้นักพัฒนา ข้อกำหนดที่ครอบคลุมและการใช้งานอ้างอิงเพื่อทำงานร่วมกันและแสดง Markdown ในลักษณะที่สอดคล้องกันระหว่างแพลตฟอร์ม”

— “ข้อมูลจำเพาะที่เป็นทางการสำหรับ GitHub Flavoured Markdown” The GitHub Blog

ในปี 2012 GitHub ได้ดำเนินการสร้างรสชาติของ Markdown ขึ้นมาเอง - GitHub Flavoured Markdown (GFM) - เพื่อต่อสู้กับการขาดมาตรฐาน Markdown และขยายไวยากรณ์ตามความต้องการ GFM ถูกสร้างขึ้นบน Sundown ซึ่งเป็น parser ที่สร้างขึ้นโดยเฉพาะโดย GitHub เพื่อแก้ไขข้อบกพร่องบางประการของตัวแยกวิเคราะห์ Markdown ที่มีอยู่ในขณะนั้น ห้าปีต่อมาในปี 2560 ทางบริษัทได้ประกาศเลิกใช้ Sundown เพื่อสนับสนุนการแยกวิเคราะห์และการเรนเดอร์ไลบรารี CommonMark โดยระบุในข้อกำหนดอย่างเป็นทางการของ GitHub Flavoured Markdown

ในส่วนคำถามทั่วไปของ Markdown และ Visual Studio Code มีการบันทึกว่า Markdown ใน VSCode กำหนดเป้าหมายข้อกำหนด CommonMark Markdown โดยใช้ไลบรารี markdown-it ซึ่งเป็นไปตามข้อกำหนด CommonMark

CommonMark ได้รับการยอมรับและนำไปใช้อย่างกว้างขวาง (ดูรายการ CommonMark Implementations) สำหรับการใช้งานในภาษาต่างๆ เช่น C (เช่น cmark), C# (เช่น CommonMark.NET), JavaScript (เช่น markdown-it) เป็นต้น นี่เป็นข่าวดีสำหรับนักพัฒนา และผู้เขียนก็ค่อยๆ เคลื่อนไปสู่ขอบเขตใหม่ที่สามารถใช้ Markdown ได้โดยมีไวยากรณ์ที่สอดคล้องกันและข้อกำหนดมาตรฐาน

หมายเหตุสั้น ๆ เกี่ยวกับ Markdown Parsers

ตัวแยกวิเคราะห์ Markdown เป็นหัวใจสำคัญของการแปลงข้อความ Markdown เป็น HTML ทั้งทางตรงและทางอ้อม

Parsers เช่น cmark และ commonmark.js จะไม่แปลง Markdown เป็น HTML โดยตรง แต่จะแปลงเป็น Abstract Syntax Tree (AST) แล้วแสดง AST เป็น HTML ทำให้กระบวนการละเอียดยิ่งขึ้นและอาจต้องมีการจัดการ ในระหว่างการแยกวิเคราะห์ — เป็น AST — และแสดงผล — เป็น HTML — ตัวอย่างเช่น ข้อความ Markdown สามารถขยายได้

รองรับไวยากรณ์ Markdown ของ CommonMark

โปรเจ็กต์หรือแพลตฟอร์มที่ใช้ข้อกำหนด CommonMark เป็นพื้นฐานของรสชาติเฉพาะมักจะถูกแทนที่ด้วย ชุดย่อยที่เข้มงวด ของข้อกำหนด CommonMark Markdown โดยส่วนใหญ่แล้ว CommonMark ได้ลดความคลุมเครือหลายอย่างโดยการสร้างข้อมูลจำเพาะที่สร้างขึ้นเพื่อสร้างขึ้น GFM เป็นตัวอย่างที่สำคัญ ในขณะที่รองรับทุกรูปแบบ CommonMark แต่ก็ยังขยายให้เหมาะสมกับการใช้งาน

การสนับสนุนไวยากรณ์ของ CommonMark อาจถูกจำกัดในตอนแรก ตัวอย่างเช่น ไม่มีการสนับสนุนสำหรับไวยากรณ์ของตารางนี้ แต่สิ่งสำคัญคือต้องรู้ว่านี่คือการออกแบบ ตามที่ความคิดเห็นนี้ในเธรดการสนทนานี้เปิดเผยว่า ไวยากรณ์ที่ได้รับการสนับสนุน นั้น เข้มงวด และกล่าวว่า เพื่อเป็น แกนหลัก ของภาษาเอง — แบบเดียวกับที่ John Gruber ผู้สร้างระบุไว้ใน Markdown: Syntax

ในขณะที่เขียน ต่อไปนี้คือไวยากรณ์ที่สนับสนุนจำนวนหนึ่ง:

1. ย่อหน้าและตัวแบ่งบรรทัด
2. ส่วนหัว
3. เน้นและเน้นที่แข็งแกร่ง,
4. กฎแนวนอน
5. รายการ
6. ลิงค์
7. รูปภาพ
8. บล็อกโควต
9. รหัส,
10. โค้ดบล็อค.

เพื่อทำตามตัวอย่าง ขอแนะนำให้คุณใช้ตัวแก้ไข commonmark.js dingus เพื่อลองใช้ไวยากรณ์และรับการแสดงตัวอย่างที่แสดงผล, HTML ที่สร้างขึ้น และ AST

ย่อหน้าและตัวแบ่งบรรทัด

ใน Markdown ย่อหน้าคือบรรทัดข้อความต่อเนื่องที่คั่นด้วยบรรทัดว่างอย่างน้อย

กฎต่อไปนี้กำหนดย่อหน้า:

1. ย่อหน้า Markdown จะแสดงใน HTML เป็นองค์ประกอบย่อหน้า <p>
2. ย่อหน้าต่างๆ จะถูกคั่นด้วยบรรทัดว่างตั้งแต่หนึ่งบรรทัดขึ้นไป
3. สำหรับการขึ้นบรรทัดใหม่ ย่อหน้าควรต่อท้ายด้วยช่องว่างสองช่อง (หรือเทียบเท่าแท็บ) หรือแบ็กสแลช ( \ )

• บทช่วยสอนเชิงโต้ตอบเพื่อเรียนรู้เกี่ยวกับย่อหน้า
• ลิงก์ถาวรของ Dingus ดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับย่อหน้า

หัวเรื่อง

ส่วนหัวใน Markdown แสดงถึงองค์ประกอบหัวเรื่อง HTML อย่างใดอย่างหนึ่ง มีสองวิธีในการกำหนดหัวเรื่อง:

1. หัวเรื่อง ATX
2. หัวเรื่อง Settext

กฎต่อไปนี้กำหนดส่วนหัว ATX:

1. รองรับหัวเรื่องระดับ 1 ( h1 ) ถึงระดับหัวเรื่อง 6 ( h6 )
2. หัวเรื่องสไตล์ Atx นำหน้าด้วยสัญลักษณ์แฮช ( # )
3. อย่างน้อยต้องมีช่องว่างคั่นข้อความและสัญลักษณ์แฮช ( # )
4. การนับแฮชจะเท่ากับเลขคาร์ดินัลของหัวข้อ หนึ่งแฮชคือ h1 สองแฮช h2 , 6 hashes, h6
5. นอกจากนี้ยังสามารถใส่จำนวนสัญลักษณ์แฮชต่อท้ายหัวเรื่องได้ตามอำเภอใจ แม้ว่าสิ่งนี้จะไม่ทำให้เกิดผลใดๆ (เช่น # Heading 1 # )

กฎต่อไปนี้กำหนดส่วนหัว Setext:

1. รองรับเฉพาะส่วนหัวระดับ 1 (h1) และส่วนหัวระดับ 2 (h2)
2. คำจำกัดความสไตล์ Setext ทำได้ด้วยเครื่องหมายเท่ากับ (=) และเครื่องหมายขีดตามลำดับ
3. เมื่อใช้ Setext ต้องมีสัญลักษณ์เท่ากับหรือเครื่องหมายขีดอย่างน้อยหนึ่งสัญลักษณ์

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับหัวข้อ
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับส่วนหัว ATX
• เรียนรู้เพิ่มเติมเกี่ยวกับส่วนหัว Setext

เน้นย้ำและเน้นหนัก

การเน้นใน Markdown สามารถเป็นตัวเอียงหรือตัวหนา (เน้นหนัก)

กฎต่อไปนี้กำหนดความสำคัญ:

1. การเน้นแบบธรรมดาและแบบเข้มข้นจะแสดงใน HTML เป็นองค์ประกอบ Emphasis, <em> และ Strong <strong> ตามลำดับ
2. ข้อความที่มีเครื่องหมายดอกจันเดียว ( * ) หรือขีดล่าง ( _ ) จะเป็นการเน้นข้อความ
3. ข้อความที่ล้อมรอบด้วยเครื่องหมายดอกจันคู่หรือขีดล่างจะเป็นการเน้นหนัก
4. สัญลักษณ์ที่มีขอบเขต (ดอกจันหรือขีดล่าง) ต้องตรงกัน
5. ต้องไม่มีช่องว่างระหว่างสัญลักษณ์และข้อความที่แนบมา

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับการเน้น
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับการเน้นและการเน้นหนัก

กฎแนวนอน

กฎแนวนอน <hr/> ถูกสร้างด้วยเครื่องหมายดอกจัน ( * ) สามตัวขึ้นไป ขีดกลาง ( - ) หรือขีดล่าง ( _ ) ในบรรทัดใหม่ สัญลักษณ์จะถูกคั่นด้วยช่องว่างจำนวนเท่าใดก็ได้ หรือไม่เลยก็ได้

• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับการแบ่งเฉพาะ

รายการ

รายการใน Markdown เป็นรายการสัญลักษณ์แสดงหัวข้อย่อย (ไม่เรียงลำดับ) หรือรายการที่เรียงลำดับ

กฎต่อไปนี้กำหนดรายการ:

1. รายการสัญลักษณ์แสดงหัวข้อย่อยจะแสดงเป็น HTML เป็นองค์ประกอบรายการที่ไม่เรียงลำดับ <ul>
2. รายการที่เรียงลำดับจะแสดงใน HTML เป็นองค์ประกอบรายการสั่งซื้อ <ol>
3. รายการสัญลักษณ์แสดงหัวข้อย่อยใช้เครื่องหมายดอกจัน เครื่องหมายบวก และขีดกลางเป็นเครื่องหมาย
4. รายการที่เรียงลำดับใช้ตัวเลขตามด้วยจุดหรือวงเล็บปิด
5. ตัวทำเครื่องหมายจะต้องสอดคล้องกัน (คุณต้องใช้เครื่องหมายที่คุณเริ่มต้นด้วยสำหรับคำจำกัดความรายการที่เหลือเท่านั้น)

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับรายการ
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับรายการ

ลิงค์

ลิงก์ได้รับการสนับสนุนด้วยรูป แบบอินไลน์ และ การอ้างอิง

กฎต่อไปนี้กำหนดลิงค์:

1. ลิงก์จะแสดงเป็นองค์ประกอบ HTML Anchor <a>
2. รูปแบบอินไลน์มีไวยากรณ์: [value](URL "optional-title") โดยไม่มีช่องว่างระหว่างวงเล็บ
3. รูปแบบการอ้างอิงมีไวยากรณ์: [value][id] สำหรับการอ้างอิง และ [id]: href "optional-title" สำหรับป้ายกำกับไฮเปอร์ลิงก์ โดยคั่นด้วยบรรทัดอย่างน้อยหนึ่งบรรทัด
4. id เป็น ตัวระบุคำจำกัดความ และอาจประกอบด้วยตัวอักษร ตัวเลข ช่องว่าง และเครื่องหมายวรรคตอน
5. ตัวระบุคำจำกัดความไม่คำนึงถึงขนาดตัวพิมพ์
6. นอกจากนี้ยังมีการรองรับลิงค์อัตโนมัติ โดยที่ URL ถูกล้อมรอบด้วยสัญลักษณ์น้อยกว่า (<) และมากกว่า (>) และแสดงตามตัวอักษร

 <!--Markdown--> [Google](https://google.com “Google”) <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> [Google](https://google.com) <!--Rendered HTML--> <a href="https://google.com">Google</a> <!--Markdown--> [Comparing Styling Methods in Next.js](/2020/09/comparing-styling-methods-next-js) <!--Rendered HTML--> <a href="/2020/09/comparing-styling-methods-next-js">Comparing Styling Methods In Next.js</a> <!--Markdown--> [Google][id] <!--At least a line must be in-between--> <!--Rendered HTML--> <a href="https://google.com" title="Google">Google</a> <!--Markdown--> <https://google.com> <!--Rendered HTML--> <a href="https://google.com">google.com</a> <!--Markdown--> <[email protected]> <!--Rendered HTML--> <a href="mailto:[email protected]">[email protected]</a>

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับลิงก์
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับลิงค์

รูปภาพ

รูปภาพใน Markdown เป็นไปตามรูป แบบอินไลน์ และ การอ้างอิง สำหรับลิงก์

กฎต่อไปนี้กำหนดภาพ:

1. รูปภาพจะแสดงเป็นองค์ประกอบรูปภาพ HTML <img>
2. รูปแบบอินไลน์มีไวยากรณ์: ![alt text](image-url "optional-title")
3. รูปแบบการอ้างอิงมีรูปแบบดังนี้: ![alt text][id] สำหรับการอ้างอิง และ [id]: image-url "optional-title" สำหรับป้ายกำกับรูปภาพ ทั้งสองควรคั่นด้วยบรรทัดว่างอย่างน้อย
4. ชื่อภาพเป็นทางเลือก และ URL รูปภาพสามารถสัมพันธ์กันได้

 <!--Markdown--> ![alt text](image-url "optional-title") <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" /> <!--Markdown--> ![alt text][id] <!--At least a line must be in-between--> <!--Markdown--> <!--Rendered HTML--> <img src="image-url" alt="alt text" title="optional-title" />

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับภาพ
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับรูปภาพ

Blockquotes

องค์ประกอบ HTML Block Quotation <blockquote> สามารถสร้างได้โดยขึ้นบรรทัดใหม่ด้วยสัญลักษณ์มากกว่า ( > )

 <!--Markdown--> > This is a blockquote element > You can start every new line > with the greater than symbol. > That gives you greater control > over what will be rendered. <!--Rendered HTML--> <blockquote> <p>This is a blockquote element You can start every new line with the greater than symbol. That gives you greater control over what will be rendered.</p> </blockquote>

Blockquotes สามารถซ้อนกันได้:

 <!--Markdown--> > Blockquote with a paragraph >> And another paragraph >>> And another <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <blockquote> <p>And another paragraph</p> <blockquote> <p>And another</p> </blockquote> </blockquote> </blockquote>

นอกจากนี้ยังสามารถมีองค์ประกอบ Markdown อื่นๆ เช่น ส่วนหัว โค้ด รายการ และอื่นๆ

 <!--Markdown--> > Blockquote with a paragraph > # Heading 1 > Heading 2 > - > 1. One > 2. Two <!--Rendered HTML--> <blockquote> <p>Blockquote with a paragraph</p> <h1>Heading 1</h1> <h2>Heading 2</h2> <ol> <li>One</li> <li>Two</li> </ol> </blockquote>

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับ blockquotes
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับ Blockquotes

รหัส

นอกจากนี้ยังรองรับองค์ประกอบ HTML Inline Code <code> หากต้องการสร้าง ให้คั่นข้อความด้วยเครื่องหมายย้อนกลับ (`) หรือเครื่องหมายย้อนกลับสองครั้งหากต้องการให้มีเครื่องหมายย้อนกลับตามตัวอักษรในข้อความที่ล้อมรอบ

 <!--Markdown--> `inline code snippet` <!--Rendered HTML--> <code>inline code snippet</code> <!--Markdown--> `<button type='button'>Click Me</button>` <!--Rendered HTML--> <code><button type='button'>Click Me</button></code> <!--Markdown--> `` There's an inline back-tick (`). `` <!--Rendered HTML--> <code>There's an inline back-tick (`).</code>

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับโค้ด
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับช่วงโค้ด

โค้ดบล็อค

นอกจากนี้ยังรองรับองค์ประกอบข้อความที่จัดรูปแบบ HTML ล่วงหน้า <pre> สามารถทำได้โดยใช้ back-tick ( ` ) หรือ tildes ( ~ ) อย่างน้อย 3 อันและจำนวนเท่ากัน — ปกติจะเรียกว่า code-fence หรือขึ้นบรรทัดใหม่โดยเริ่มต้นการเยื้องอย่างน้อย 4 ช่องว่าง

 <!--Markdown--> ``` const dedupe = (array) => [...new Set(array)]; ``` <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre> <!--Markdown--> const dedupe = (array) => [...new Set(array)]; <!--Rendered HTML--> <pre><code>const dedupe = (array) => [...new Set(array)];</code></pre>

• บทแนะนำแบบโต้ตอบเพื่อเรียนรู้เกี่ยวกับโค้ด
• ลิงก์ถาวรของ Dingus เพื่อดูตัวอย่างแบบเต็มด้วยการแสดงตัวอย่างและ AST
• เรียนรู้เพิ่มเติมเกี่ยวกับบล็อกรหัส Fenced และ Indented

การใช้ HTML แบบอินไลน์

ตามหมายเหตุข้อมูลจำเพาะดั้งเดิมของ John Grubers ใน HTML แบบอินไลน์ มาร์กอัปใดๆ ที่ไม่ครอบคลุมโดยไวยากรณ์ของ Markdown คุณสามารถใช้ HTML ได้เอง โดย มีข้อจำกัดเพียงอย่างเดียวคือองค์ประกอบ HTML ระดับบล็อก — เช่น <div> , <table> , <pre> , <p> ฯลฯ — ต้องแยกออกจากเนื้อหาโดยรอบด้วยบรรทัดว่าง และแท็กเริ่มต้นและสิ้นสุดของบล็อกไม่ควรเยื้องด้วยแท็บหรือช่องว่าง

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

ดำเนินต่อไป

CommonMark กำลังดำเนินการอยู่อย่างต่อเนื่องโดยมีข้อมูลจำเพาะที่อัปเดตล่าสุดเมื่อวันที่ 6 เมษายน 2019 มีแอปพลิเคชันยอดนิยมจำนวนหนึ่งที่สนับสนุนมันในกลุ่มเครื่องมือ Markdown ด้วยความตระหนักในความพยายามของ CommonMark ในการสร้างมาตรฐาน ฉันคิดว่ามันเพียงพอแล้วที่จะสรุปว่าในความเรียบง่ายของ Markdown มีการทำงานมากมายอยู่เบื้องหลัง และเป็นสิ่งที่ดีสำหรับความพยายามของ CommonMark ที่ข้อกำหนดอย่างเป็นทางการของ GitHub Flavoured Markdown ขึ้นอยู่กับข้อกำหนด

การย้ายไปสู่ความพยายามในการสร้างมาตรฐานของ CommonMark ไม่ได้ป้องกันการสร้างรสชาติเพื่อขยายไวยากรณ์ที่รองรับ และในขณะที่ CommonMark เตรียมพร้อมสำหรับรุ่น 1.0 ที่มีปัญหาที่ต้องแก้ไข มีแหล่งข้อมูลที่น่าสนใจเกี่ยวกับความพยายามอย่างต่อเนื่องที่คุณสามารถใช้สำหรับ การตรวจตรา

ทรัพยากร

• แนะนำ Markdown โดย John Gruber
• เว็บไซต์อย่างเป็นทางการของ CommonMark
• GitHub Flavoured Markdown Spec
• cmark repo อย่างเป็นทางการ
• ส้อม cmark . ของ GitHub
• Markdown บน Wikipedia
• คู่มือมาร์กอัป