การแสดงสี่เหลี่ยมสีใน AsciiDoc: คู่มือปฏิบัติ

บทนำ

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

ประเด็นปัญหา

บริบทการใช้งาน

สมมติว่าคุณกำลังจัดทำเอกสารตัวแปร CSS ของธีมแอปพลิเคชันเว็บ คุณต้องการ:

แสดงรายการรหัสสีแบบเลขฐานสิบหก
แสดงตัวอย่างภาพของแต่ละสี
รักษาความสามารถในการอ่านของเอกสารต้นฉบับ
รับรองความเข้ากันได้กับเครื่องมือสร้างไซต์แบบสแตติก เช่น JBake

@startuml
left to right direction
skinparam packageStyle rectangle

actor "นักเขียนเทคนิค" as writer
actor "ผู้อ่าน" as reader

rectangle "เอกสาร AsciiDoc" {
  usecase "จัดทำเอกสารพาเลตต์สี" as UC1
  usecase "แสดงรหัสเลขฐานสิบหก" as UC2
  usecase "แสดงตัวอย่างสี" as UC3
  usecase "สร้างเว็บไซต์แบบสแตติก" as UC4
  usecase "เปิดดูเอกสาร" as UC5
}

writer --> UC1
UC1 ..> UC2 : include
UC1 ..> UC3 : include
UC1 --> UC4
UC4 --> UC5
UC5 <-- reader
@enduml

แนวทางที่เป็นไปได้

สามารถพิจารณาหลายวิธีในการแสดงสีในเอกสาร AsciiDoc:

@startuml
skinparam componentStyle rectangle

package "วิธีแก้ไขที่เป็นไปได้" {
  component "อักขระ Unicode" as unicode
  component "รูปภาพภายนอก" as images
  component "บทบาท CSS ที่กำหนดเอง" as css
  component "การแทรก HTML" as html
}

package "เกณฑ์การประเมิน" {
  component "ความเรียบง่าย" as simple
  component "ความสามารถในการพอร์ต" as portable
  component "การปรับแต่ง" as custom
  component "การบำรุงรักษา" as maintain
}

unicode -down-> simple : ✓
unicode -down-> portable : ✓
unicode -down-> custom : ✗

images -down-> simple : ✗
images -down-> portable : ✗
images -down-> custom : ✓

css -down-> simple : ~
css -down-> portable : ✗
css -down-> custom : ✓

html -down-> simple : ✓
html -down-> portable : ✓
html -down-> custom : ✓✓
html -down-> maintain : ✓

note right of html
โซลูชันที่แนะนำ
end note
@enduml

ตัวเลือก 1 : อักขระยูนิโคด

การใช้ตัวอักษร Unicode เช่น`■`(■) นั้นเรียบง่ายแต่มีข้อจำกัด :

* ■ --accent-color: #7952b3 (violet Bootstrap)

ข้อจำกัด : ไม่สามารถควบคุมสีได้ ขึ้นอยู่กับฟอนต์ของระบบ

ตัวเลือก 2 : รูปภาพภายนอก

สร้างภาพ PNG หรือ SVG สำหรับแต่ละสี:

* image:colors/violet.svg[width=16] --accent-color: #7952b3

ข้อจำกัด : การบำรุงรักษาหนัก การเพิ่มจำนวนไฟล์ และไม่มีการซิงโครไนซ์อัตโนมัติ

ตัวเลือก 3 : บทบาท CSS ที่กำหนดเอง

กำหนดคลาส CSS และนำไปใช้ผ่านโรล AsciiDoc:

* [.color-violet]##■## --accent-color: #7952b3

ข้อจำกัด : ต้องมีสไตล์ชีตภายนอก และต้องกำหนดสีที่เป็นไปได้ทั้งหมดไว้ล่วงหน้า

ตัวเลือก 4: การฉีด HTML (แนวทางที่เลือกใช้)

ใช้แมโคร``เพื่อแทรก HTML พร้อมสไตล์อินไลน์:

* pass:[<span style="display:inline-block;width:1em;height:1em;
background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: #7952b3 (violet Bootstrap)

วิธีแก้ปัญหา: การฉีด HTML ด้วย

หลักการทำงาน

มาโคร``ของ AsciiDoc ช่วยให้สามารถแทรกเนื้อหาดิบที่ไม่ถูกตีความโดยโปรเซสเซอร์ AsciiDoc ซึ่งช่วยให้เราแทรก HTML โดยตรงพร้อมสไตล์ CSS แบบอินไลน์

@startuml
participant "เอกสาร\nAsciiDoc" as doc
participant "โปรเซสเซอร์\nAsciiDoc" as processor
participant "มาโคร pass:[]" as pass
participant "HTML\nสุดท้าย" as html

doc -> processor : Analyse document
processor -> pass : Détecte pass:[]
pass -> processor : Retourne HTML brut
processor -> html : Insère sans transformation
html -> html : Navigateur applique styles
@enduml

การนำไปใช้งาน

นี่คือโครงสร้าง HTML ที่จะแทรก:

<span style="display:inline-block;
             width:1em;
             height:1em;
             background:#7952b3;
             vertical-align:middle;
             margin-right:0.5em">
</span>

คำอธิบายคุณสมบัติ CSS

ทรัพย์สิน ฟังก์ชัน

ทรัพย์สิน	ฟังก์ชัน
`display:inline-block`	ทำให้สามารถกำหนด width/height ได้โดยยังคงอยู่ในฟลวแบบอินไลน์
`width:1em; height:1em`	ขนาดของสี่เหลี่ยมจัตุรัสสัมพันธ์กับขนาดตัวอักษร (responsive)
`background:#7952b3`	สีที่จะแสดง (แปรผันตามความต้องการของคุณ)
`vertical-align:middle`	จัดตำแหน่งสี่เหลี่ยมให้ตรงกับข้อความที่อยู่ติดกัน
`margin-right:0.5em`	ระยะห่างระหว่างสี่เหลี่ยมจัตุรัสกับข้อความ

display:inline-block

ทำให้สามารถกำหนด width/height ได้โดยยังคงอยู่ในฟลวแบบอินไลน์

width:1em; height:1em

ขนาดของสี่เหลี่ยมจัตุรัสสัมพันธ์กับขนาดตัวอักษร (responsive)

background:#7952b3

สีที่จะแสดง (แปรผันตามความต้องการของคุณ)

vertical-align:middle

จัดตำแหน่งสี่เหลี่ยมให้ตรงกับข้อความที่อยู่ติดกัน

margin-right:0.5em

ระยะห่างระหว่างสี่เหลี่ยมจัตุรัสกับข้อความ

ตัวอย่างที่สมบูรณ์

นี่คือตัวอย่างที่บันทึกชุดสีของธีม:

== Thème Clair

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#61428f;vertical-align:middle;margin-right:0.5em"></span>] --accent-hover: `#61428f` (violet plus foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --card-bg: `#ffffff` (blanc)

ใครสร้างผลลัพธ์ต่อไปนี้:

ธีมสว่าง

--bg-primary:`#f8f9fa`(ขาวนวล)
--text-primary:`#212529`(สีดำเข้มมาก)
--accent-color:`#7952b3`(Bootstrap สีม่วง)
--accent-hover:`#61428f`(สีม่วงเข้มขึ้น)
--card-bg:`#ffffff`(ขาว)

การปรับให้เหมาะสมและแนวปฏิบัติที่ดีที่สุด

จัดการสีอ่อน

สำหรับสีที่อ่อนมาก (สีขาว, สีเทาอ่อนมาก) ให้เพิ่มเส้นขอบเพื่อให้มองเห็นได้บนพื้นหลังสีขาว:

<span style="display:inline-block;width:1em;height:1em;
background:#ffffff;border:1px solid #ccc;
vertical-align:middle;margin-right:0.5em"></span>

ขอบสีเทา (border:1px solid #ccc) ช่วยกำหนดขอบเขตของสี่เหลี่ยมสีขาวบนพื้นหลังสีขาว

ปรับขนาดของสี่เหลี่ยมจัตุรัส

คุณสามารถปรับขนาดของสี่เหลี่ยมตามความต้องการของคุณ:

* pass:[<span style="display:inline-block;width:1.5em;height:1.5em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Grand carré
* pass:[<span style="display:inline-block;width:0.8em;height:0.8em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] Petit carré

การใช้หน่วย`em`รับประกันว่าสี่เหลี่ยมจะปรับให้เข้ากับขนาดตัวอักษร

สร้างตัวแปร

สำหรับความต้องการเฉพาะ คุณสามารถสร้างรูปแบบต่างๆ ได้:

วงกลมสี

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;border-radius:50%;vertical-align:middle;margin-right:0.5em"></span>] Cercle violet

สี่เหลี่ยมจัตุรัสพร้อมขอบสี

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:3px solid #7952b3;vertical-align:middle;margin-right:0.5em"></span>] Bordure violette

สถาปัตยกรรมของโซลูชัน

@startuml
package "เวิร์กโฟลว์เอกสาร" {
  [Document AsciiDoc\navec pass macro] as asciidoc
  [Processeur JBake] as jbake
  [Site HTML statique] as html
  [Navigateur Web] as browser
}

asciidoc --> jbake : 1. Compilation
jbake --> html : 2. Génération
html --> browser : 3. Affichage
browser --> browser : 4. Rendu CSS

note right of asciidoc
มีแท็ก pass:[] พร้อม HTML แบบอินไลน์
end note

note right of jbake
คง HTML ไว้ใน pass:[]
end note

note right of browser
ใช้สไตล์
inline CSS
end note
@enduml

ข้อดีและข้อจำกัด

ข้อดี

✓ ความเป็นอิสระ : ไม่ต้องพึ่งพาไฟล์ภายนอก
✓ ความสามารถในการพอร์ต : ทำงานได้กับโปรเซสเซอร์ AsciiDoc ทั้งหมด
✓ การซิงโครไนซ์ : โค้ดสีอยู่ใน HTML โดยตรง
✓ ความยืดหยุ่น : การปรับแต่งสไตล์อย่างสมบูรณ์
✓ การบำรุงรักษา : การแก้ไขโค้ดเลขฐานสิบหกอย่างง่าย
✓ ความเข้ากันได้กับ JBake : ทำงานได้อย่างสมบูรณ์แบบกับเครื่องมือสร้างเว็บไซต์แบบสแตติก

ข้อจำกัด

✗ ความเยิ่นเย้อ : โค้ด HTML ที่ซ้ำซากในซอร์ส AsciiDoc
✗ ความอ่านง่ายของต้นฉบับ : เอกสารต้นฉบับมีความเรียบง่ายน้อยกว่า
✗ การเข้าถึง : ไม่มีข้อความทางเลือกแบบเนทีฟ (ต้องเพิ่มด้วยตนเอง)

การปรับปรุงการเข้าถึง

เพื่อทำให้สี่เหลี่ยมเข้าถึงได้สำหรับโปรแกรมอ่านหน้าจอ:

* pass:[<span role="img" aria-label="Couleur violet Bootstrap"
style="display:inline-block;width:1em;height:1em;background:#7952b3;
vertical-align:middle;margin-right:0.5em"></span>]
--accent-color: `#7952b3` (violet Bootstrap)

แอตทริบิวต์`role="img"` et `aria-label`ช่วยให้เทคโนโลยีสิ่งอำนวยความสะดวกสามารถเข้าใจและอธิบายเนื้อหาภาพได้

ตัวอย่างที่เป็นรูปธรรม: เอกสารประกอบธีม

นี่คือตัวอย่างที่สมบูรณ์ซึ่งแสดงให้เห็นหลายธีม:

= Guide des couleurs de l'application

== Thème Clair (`:root`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#f8f9fa;border:1px solid #ccc;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#f8f9fa` (blanc cassé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#7952b3;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#7952b3` (violet Bootstrap)

== Thème Sombre (`[data-bs-theme="dark"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#212529;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#212529` (noir très foncé)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #999;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#0d6efd;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#0d6efd` (bleu Bootstrap)

== Thème Contraste Élevé (`[data-bs-theme="high-contrast"]`)

* pass:[<span style="display:inline-block;width:1em;height:1em;background:#000000;vertical-align:middle;margin-right:0.5em"></span>] --bg-primary: `#000000` (noir)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#ffffff;border:1px solid #000;vertical-align:middle;margin-right:0.5em"></span>] --text-primary: `#ffffff` (blanc)
* pass:[<span style="display:inline-block;width:1em;height:1em;background:#00ff00;vertical-align:middle;margin-right:0.5em"></span>] --accent-color: `#00ff00` (vert vif)

บทสรุป

การฉีด HTML ผ่านมาโคร``ของ AsciiDoc นำเสนอโซลูชันที่เรียบหรูและใช้งานได้จริงสำหรับการแสดงตัวอย่างสีในเอกสารทางเทคนิค แม้จะค่อนข้างเยิ่นเย้อเล็กน้อย วิธีนี้รับประกันความสามารถในการพอร์ตสูงสุดและการบำรุงรักษาที่ง่ายขึ้น

เทคนิคนี้ไม่จำเป็นต้องมีการกำหนดค่าภายนอกใด ๆ ไม่ต้องใช้สไตล์ชีตเพิ่มเติม และทำงานได้ทันทีกับ JBake และตัวประมวลผล AsciiDoc มาตรฐานทั้งหมด

เมื่อคุณสร้างสี่เหลี่ยมสีแรกของคุณแล้ว เพียงคัดลอกและวางโค้ด HTML และแก้ไขโค้ดเลขฐานสิบหกเพื่อสร้างชุดสีที่สมบูรณ์ได้อย่างรวดเร็ว

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

แหล่งข้อมูล

บทความเผยแพร่เมื่อ 2025-11-01

บทความที่เกี่ยวข้อง

HyperFrames-Gradle : Transformer l'AsciiDoc en Vidéo MP4
31 May 2026

Audit de ma Consommation LLM : SQLite, OpenCode, Ollama Cloud, et Pourquoi Mon Abonnement Pro Éclate le Marché Mondial
18 May 2026

สถาปัตยกรรม « Plugin อิสระ + Root ฝั่งผู้บริโภค » : ทำไม Gradle Builds ของฉันจึงซ้ำซ้อน
14 May 2026

Le Knowledge Graph comme moteur de recommandation : comment j'ai tué les « articles connexes » chronologiques
12 May 2026

กรุณาเปิดใช้งาน JavaScript เพื่อดู ความคิดเห็นโดย Disqus.