รายการคำจำกัดความ (Definition Lists)

Definition List เป็นความสามารถแบบขยายของ Markdown ใช้สำหรับสร้างรายการคำศัพท์และคำจำกัดความ มักใช้ทำอภิธานศัพท์ อธิบายคำศัพท์ หรืออธิบายพารามิเตอร์

ไวยากรณ์พื้นฐาน

รูปแบบพื้นฐาน

รูปแบบพื้นฐานจะมี “คำศัพท์” อยู่บรรทัดหนึ่ง และบรรทัดถัดมาเป็น “คำจำกัดความ” ที่ขึ้นต้นด้วยเครื่องหมายโคลอน ::

Term
: Definition content

ผลลัพธ์ที่เรนเดอร์:

Term : Definition content

หลายคำและหลายคำจำกัดความ

Markdown
: A lightweight markup language
: Created by John Gruber in 2004

HTML
: A standard markup language used to create web pages
: Used to create web pages

ผลลัพธ์ที่เรนเดอร์:

Markdown : A lightweight markup language : Created by John Gruber in 2004

HTML : A standard markup language used to create web pages : Used to create web pages

การใช้งานขั้นสูง

คำจำกัดความหลายบรรทัด

คำจำกัดความสามารถมีหลายบรรทัดได้ โดยบรรทัดถัด ๆ ไปต้องมีการเยื้อง (indent) อย่างน้อยหนึ่งช่องว่าง:

Term
: This is the first line of definition content
   This is the second line, needs at least one space indentation
  
   This is a new paragraph, needs at least one space indentation and a preceding blank line

ผลลัพธ์ที่เรนเดอร์:

Term : This is the first line of definition content This is the second line, needs at least one space indentation

This is a new paragraph, needs at least one space indentation and a preceding blank line

ใช้องค์ประกอบ Markdown อื่น ๆ ในคำจำกัดความ

ภายในคำจำกัดความสามารถใส่องค์ประกอบ Markdown อื่น ๆ ได้ เช่น ลิงก์ การเน้นข้อความ โค้ด เป็นต้น:

Markdown Syntax
: **Markdown** supports multiple text formatting:
  - *Italic* and **Bold**
  - [Link](https://www.markdownlang.com)
  - `Inline code`
  - > Block quote
  - Lists and other elements

ผลลัพธ์ที่เรนเดอร์:

Markdown Syntax : Markdown supports multiple text formatting:

• Italic and Bold
• Link
• Inline code

• Block quote

• Lists and other elements

รายการคำจำกัดความแบบซ้อน (Nested)

ในบางตัวเรนเดอร์ของ Markdown สามารถสร้างรายการคำจำกัดความแบบซ้อนได้:

Outer Term
: Outer Definition

   Inner Term
  : Inner Definition
  : Another Inner Definition

ผลลัพธ์ที่เรนเดอร์ (บนแพลตฟอร์มที่รองรับ):

Outer Term : Outer Definition

Inner Term : Inner Definition : Another Inner Definition

ความเข้ากันได้และความแตกต่างในการใช้งาน

การรองรับบนแพลตฟอร์มต่าง ๆ

แพลตฟอร์ม/เครื่องมือ	รองรับ Definition List	ไวยากรณ์พิเศษ	รองรับการซ้อน
GitHub Markdown	❌	-	-
GitLab Markdown	✅	Standard	✅
Jekyll (kramdown)	✅	Standard	✅
Hugo	✅	Standard	✅
CommonMark	❌	-	-
VitePress	✅	Standard	✅
Pandoc	✅	Standard	✅

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

เครื่องมือ Markdown ส่วนใหญ่จะแปลง Definition List เป็น HTML องค์ประกอบ <dl>, <dt> และ <dd>:

<dl>
  <dt>Term</dt>
  <dd>Definition content</dd>
  
  <dt>Another Term</dt>
  <dd>Another Definition</dd>
</dl>

ความแปรผันของไวยากรณ์

ตัวเรนเดอร์บางตัวอาจต้องการรูปแบบไวยากรณ์ที่แตกต่างเล็กน้อย:

<!-- Standard Syntax -->
Term
: Definition

<!-- Compact Syntax (some processors) -->
Term: Definition

<!-- Extra space syntax (some processors) -->
Term
  : Definition

กรณีใช้งาน

อภิธานศัพท์

Definition List เหมาะอย่างยิ่งสำหรับสร้างอภิธานศัพท์หรือคำศัพท์เฉพาะ:

## Programming Glossary

API
: An application programming interface, a set of rules that allow different software applications to communicate with each other.

Framework
: A software library that provides a standardized structure for application development.

Git
: A distributed version control system used to track changes in a project development process.

IDE
: An integrated development environment, a software application that includes a code editor and various development tools.

ผลลัพธ์ที่เรนเดอร์:

Programming Glossary

API : An application programming interface, a set of rules that allow different software applications to communicate with each other.

Framework : A software library that provides a standardized structure for application development.

Git : A distributed version control system used to track changes in a project development process.

IDE : An integrated development environment, a software application that includes a code editor and various development tools.

เอกสาร API

มักใช้ Definition List ในเอกสาร API เพื่ออธิบายพารามิเตอร์หรือออปชัน:

## Request Parameters

user_id
: **Required** - The unique identifier for the user.
: Type: `integer`

name
: **Optional** - The display name for the user.
: Type: `string`
: Default: `null`

status
: **Optional** - The user status.
: Type: `string`
: Allowed values: `active`, `inactive`, `suspended`
: Default: `active`

ผลลัพธ์ที่เรนเดอร์:

Request Parameters

user_id : Required - The unique identifier for the user. : Type: integer

name : Optional - The display name for the user. : Type: string : Default: null

status : Optional - The user status. : Type: string : Allowed values: active, inactive, suspended : Default: active

หมายเหตุการกำหนดค่า

Definition List ยังเหมาะสำหรับอธิบายตัวเลือกการกำหนดค่า:

## Configuration Options

debug
: Enable or disable debug mode.
: Type: `boolean`
: Default: `false`
: Example: `debug: true`

log_level
: The level of detail for logging.
: Type: `string`
: Allowed values: `error`, `warn`, `info`, `debug`
: Default: `info`
: Example: `log_level: debug`

max_connections
: The maximum number of simultaneous connections allowed.
: Type: `integer`
: Default: `100`
: Example: `max_connections: 500`

แนวปฏิบัติที่ดี

ความสม่ำเสมอ

✅ แนวทางที่แนะนำ:

1. **รักษาสไตล์ของคำและคำจำกัดความให้สม่ำเสมอ**:
   - ควรใช้คำนาม/วลีที่กระชับสำหรับ "คำ"
   - คำจำกัดความควรเป็นประโยค ตัวอักษรแรกพิมพ์ใหญ่ และจบด้วยจุด
   - หากเป็นหลายบรรทัด ให้รักษาการเยื้องให้คงที่

2. **จัดกลุ่มอย่างเหมาะสม**:
   - รวมคำที่เกี่ยวข้องไว้ด้วยกัน
   - ใช้หัวเรื่องแยก Definition List คนละหมวด

3. **สำหรับคำเชิงเทคนิค**:
   - ระบุชนิด (type) ที่เกี่ยวข้อง
   - เพิ่มตัวอย่างประกอบ
   - ระบุว่าเป็นแบบจำเป็นหรือไม่บังคับ

❌ แนวทางที่ควรหลีกเลี่ยง:

1. คำยาวเกินไปจนเกินหนึ่งบรรทัด
2. ใช้รูปแบบตัวอักษรใหญ่เกินจำเป็นใน "คำ"
3. ไม่มีการจัดหมวดหมู่ที่ชัดเจน
4. คำจำกัดความมีข้อมูลที่ไม่เกี่ยวข้อง

ทางเลือกอื่น

บนแพลตฟอร์มที่ไม่รองรับ Definition List สามารถจำลองด้วยรูปแบบอื่นได้:

<!-- ใช้ตัวหนาและการเยื้อง -->
**Term**
   Definition content

**Another Term**
   Another definition content

<!-- ใช้ตาราง -->
| Term | Definition |
|------|------|
| API | Application Programming Interface |
| IDE | Integrated Development Environment |

<!-- ใช้หัวเรื่องและย่อหน้า -->
### Term
Definition content

### Another Term
Another definition content

ตัวอย่างการประยุกต์ใช้จริง

เอกสารซอฟต์แวร์

## System Requirements

Operating System
: **Windows**: Windows 10 or higher
: **macOS**: macOS 10.14 (Mojave) or higher
: **Linux**: Ubuntu 18.04+, Debian 10+, CentOS 7+

Hardware
: **Processor**: Quad-core 2.0 GHz or faster
: **Memory**: At least 8GB RAM, recommended 16GB
: **Storage**: At least 10GB available space, SSD storage

Network
: Broadband internet connection (at least 10 Mbps)
: Outbound connections allowed on ports: 80, 443, 22

เอกสารเชิงวิชาการ

## Research Terms

Dataset
: A collection of data used for analysis or evaluation.
: This study used a sample from a public repository (n=1000).

Variable
: **Independent Variable**: Input factors manipulated by the researcher.
  In this study, the independent variable was environmental temperature.
  
: **Dependent Variable**: Output factors measured in the study.
  In this study, the dependent variable was processing speed.
  
: **Control Variable**: Factors kept constant in the experiment.
  In this study, humidity and processor load were included.

Significance Level
: The probability threshold used to determine if the result is meaningful in statistical analysis.
: This study used p < 0.05 as the significance standard.

ปัญหาที่พบบ่อยและแนวทางแก้ไข

รายการคำจำกัดความไม่แสดงผล

หาก Definition List ไม่แสดงผลอย่างถูกต้อง:

1. ตรวจสอบว่าแพลตฟอร์มรองรับไวยากรณ์ Definition List หรือไม่
2. อย่าเว้นบรรทัดว่างระหว่าง “คำ” และ “คำจำกัดความ”
3. ตรวจสอบช่องว่างก่อนเครื่องหมายโคลอน (บางตัวเรนเดอร์อาจมีข้อกำหนดเฉพาะ)
4. ลองเพิ่มระดับการเยื้องหรือปรับรูปแบบไวยากรณ์

ปัญหากับรายการแบบซ้อน

รายการคำจำกัดความแบบซ้อนอาจมีปัญหาในบางตัวเรนเดอร์:

1. เพิ่มระดับการเยื้อง (เช่น ด้านในใช้ 4 หรือ 8 ช่องว่าง)
2. ใส่บรรทัดว่างระหว่างชั้นให้เหมาะสม
3. หากยังมีปัญหา ให้พิจารณาใช้โครงสร้างอื่นแทน (เช่น รายการปกติ)

ปัญหาการจัดรูปแบบ

หากการจัดรูปแบบในคำจำกัดความไม่ถูกต้อง:

1. ตรวจสอบการเยื้องของย่อหน้าและองค์ประกอบทั้งหมดให้ถูกต้อง
2. ตรวจสอบการเว้นบรรทัดระหว่างองค์ประกอบแบบบล็อก (เช่น โค้ดบล็อก รายการ) ภายในคำจำกัดความ
3. ลองเพิ่มจำนวนช่องว่างในการเยื้อง

ไวยากรณ์ที่เกี่ยวข้อง

• Lists - ไวยากรณ์รายการพื้นฐาน
• Tables - การแสดงข้อมูลเชิงโครงสร้าง
• Fenced Code Blocks - ไวยากรณ์โค้ดบล็อก

เครื่องมือและปลั๊กอิน

• markdown-it-deflist: เพิ่มการรองรับ Definition List ให้กับ markdown-it
• kramdown: ตัวแยก Markdown ที่รองรับ Definition List โดยกำเนิด
• remark-definition-list: ปลั๊กอิน Definition List สำหรับ remark parser

---

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