วิธีใช้ pandoc เพื่อแปลงไฟล์บน Linux Command Line

คุณสามารถใช้ pandoc บน Linux เพื่อแปลงไฟล์ได้มากกว่า 40 รูปแบบ คุณสามารถใช้มันเพื่อสร้างระบบ docs-as-code อย่างง่ายโดยการเขียนใน Markdown จัดเก็บใน git และเผยแพร่ในรูปแบบที่รองรับ

การแปลงเอกสารและ Docs-as-Code

หากคุณมีเอกสารในรูปแบบไฟล์ที่รองรับมากมาย pandoc's การแปลงเป็นไฟล์อื่นๆ ก็ทำได้ง่าย นั่นเป็นเครื่องมือที่มีประโยชน์!

แต่พลังที่แท้จริงของ pandoc นั้นชัดเจนเมื่อคุณใช้เป็นพื้นฐานของระบบ docs-as-code อย่างง่าย หลักการของ docs-as-code คือการนำเทคนิคและหลักการบางอย่างของการพัฒนาซอฟต์แวร์มาใช้และนำไปใช้กับการเขียนเอกสาร โดยเฉพาะอย่างยิ่งสำหรับโครงการพัฒนาซอฟต์แวร์ คุณสามารถใช้มันกับการพัฒนาเอกสารประเภทใดก็ได้

นักพัฒนาซอฟต์แวร์ใช้ตัวแก้ไขที่ชื่นชอบหรือสภาพแวดล้อมการพัฒนาแบบรวม (IDE) เพื่อเขียนโปรแกรมของตน รหัสที่พวกเขาพิมพ์จะถูกบันทึกไว้ในไฟล์ข้อความ เหล่านี้ประกอบด้วยซอร์สโค้ดสำหรับโปรแกรม

พวกเขาใช้ระบบควบคุมเวอร์ชันหรือ VCS (Git เป็นที่นิยมมากที่สุด) เพื่อบันทึกการเปลี่ยนแปลงของซอร์สโค้ดในขณะที่มีการพัฒนาและปรับปรุง ซึ่งหมายความว่าโปรแกรมเมอร์มีประวัติที่สมบูรณ์ของไฟล์ซอร์สโค้ดทุกเวอร์ชัน เขาหรือเธอสามารถเข้าถึงไฟล์เวอร์ชันก่อนหน้าได้อย่างรวดเร็ว Git เก็บไฟล์ไว้ในที่เก็บ มีที่เก็บข้อมูลในเครื่องบนคอมพิวเตอร์ของนักพัฒนาแต่ละรายและที่เก็บข้อมูลส่วนกลางที่ใช้ร่วมกันและระยะไกลซึ่งมักจะโฮสต์บนคลาวด์

เมื่อพวกเขาพร้อมที่จะสร้างโปรแกรมเวอร์ชันที่ใช้งานได้ พวกเขาจะใช้คอมไพเลอร์เพื่ออ่านซอร์สโค้ดและสร้างไฟล์ปฏิบัติการแบบไบนารี

ด้วยการเขียนเอกสารของคุณในภาษามาร์กอัปแบบข้อความที่เน้นข้อความ คุณสามารถใช้ VCS เพื่อควบคุมเวอร์ชันการเขียนของคุณได้ เมื่อคุณพร้อมที่จะแจกจ่ายหรือเผยแพร่เอกสาร คุณสามารถใช้ pandoc เพื่อสร้างเอกสารเวอร์ชันต่างๆ ได้มากเท่าที่คุณต้องการ รวมถึงแบบเว็บ (HTML) การประมวลผลคำ หรือชุดเรียงพิมพ์ (LibreOffice, Microsoft Word, TeX) , รูปแบบเอกสารแบบพกพา (PDF), e-book (ePub) เป็นต้น

คุณสามารถทำสิ่งนี้ได้จากไฟล์ข้อความน้ำหนักเบาที่ควบคุมโดยเวอร์ชันชุดเดียว

กำลังติดตั้ง pandoc

ในการติดตั้ง pandoc บน Ubuntu ให้ใช้คำสั่งนี้:

 sudo apt-get ติดตั้ง pandoc 

บน Fedora คำสั่งที่คุณต้องการมีดังต่อไปนี้:

 sudo dnf ติดตั้ง pandoc 

บน Manjaro คุณต้องพิมพ์:

 sudo pacman -Syu pandoc 

คุณสามารถตรวจสอบเวอร์ชันที่คุณติดตั้งโดยใช้ตัวเลือก --version :

 pandoc --version 

ใช้ pandoc ไม่มีไฟล์

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

ลองดูตัวอย่าง:

 pandoc 

เราได้พิมพ์ Markdown สองสามบรรทัดและกำลังจะกด Ctrl+D

ทันทีที่เราทำ pandoc จะสร้างเอาต์พุต HTML ที่เทียบเท่ากัน

ในการทำอะไรที่เป็นประโยชน์กับ pandoc เราจำเป็นต้องใช้ไฟล์จริงๆ

ข้อมูลพื้นฐานเกี่ยวกับ Markdown

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

สามารถอ่าน Markdown ได้อย่างง่ายดาย เนื่องจากไม่มีแท็กที่ยุ่งยากทางสายตาให้เบี่ยงเบนความสนใจจากข้อความ การจัดรูปแบบในเอกสาร Markdown คล้ายกับการจัดรูปแบบที่แสดง ด้านล่างนี้คือข้อมูลพื้นฐานบางส่วน:

• หากต้องการเน้นข้อความด้วย ตัวเอียง ให้ใส่เครื่องหมายดอกจัน *This will be emphasized*
• หากต้องการ ตัวหนา ให้ใช้เครื่องหมายดอกจันสองดอก **This will be in bold**
• ส่วนหัวจะแสดงด้วยเครื่องหมายตัวเลข/เครื่องหมายแฮช ( # ) ข้อความถูกแยกจากแฮชด้วยช่องว่าง ใช้แฮชหนึ่งอันสำหรับส่วนหัวระดับบนสุด สองแฮชสำหรับระดับที่สอง และอื่นๆ
• ในการสร้างรายการสัญลักษณ์แสดงหัวข้อย่อย ให้เริ่มแต่ละบรรทัดของรายการด้วยเครื่องหมายดอกจันและเว้นวรรคก่อนข้อความ
• ในการสร้างรายการลำดับเลข ให้เริ่มแต่ละบรรทัดด้วยตัวเลขตามด้วยจุด จากนั้นเว้นวรรคก่อนข้อความ
• ในการสร้างไฮเปอร์ลิงก์ ให้ใส่ชื่อไซต์ในวงเล็บเหลี่ยม ( [] ) และ URL ในวงเล็บ [ () ] ดังนี้ [Link to How to Geek](https://www.howtogeek.com/) .
• หากต้องการแทรกรูปภาพ ให้พิมพ์เครื่องหมายอัศเจรีย์ก่อนวงเล็บเหลี่ยม ( ![] ) พิมพ์ข้อความแสดงแทนรูปภาพในวงเล็บ จากนั้น ให้ใส่เส้นทางไปยังรูปภาพในวงเล็บ [ () “] นี่คือตัวอย่าง: ![The Geek](HTG.png) .

เราจะกล่าวถึงตัวอย่างเพิ่มเติมของสิ่งเหล่านี้ในหัวข้อถัดไป

ที่เกี่ยวข้อง: Markdown คืออะไรและคุณใช้งานอย่างไร?

การแปลงไฟล์

การแปลงไฟล์นั้นตรงไปตรงมา โดยทั่วไปแล้ว pandoc จะสามารถกำหนดรูปแบบไฟล์ที่คุณใช้งานจากชื่อไฟล์ได้ ที่นี่ เราจะสร้างไฟล์ HTML จากไฟล์ Markdown ตัวเลือก -o (เอาต์พุต) จะบอก pandoc ให้ทราบถึงชื่อไฟล์ที่เราต้องการสร้าง:

 pandoc -o sample.html sample.md 

ไฟล์ Markdown ตัวอย่างของเรา sample.md มีส่วนสั้น ๆ ของ Markdown ที่แสดงในภาพด้านล่าง

ไฟล์ชื่อ sample.html ถูกสร้างขึ้น เมื่อเราดับเบิลคลิกที่ไฟล์ เบราว์เซอร์เริ่มต้นของเราจะเปิดขึ้นมา

ตอนนี้ มาสร้างเอกสารข้อความรูปแบบเอกสารเปิดที่เราเปิดได้ใน LibreOffice Writer:

 pandoc -o sample.odt sample.md 

ไฟล์ ODT มีเนื้อหาเหมือนกับไฟล์ HTML

การสัมผัสที่เรียบร้อยคือข้อความแสดงแทนสำหรับรูปภาพที่ใช้เพื่อสร้างคำบรรยายสำหรับรูปภาพโดยอัตโนมัติ

การระบุรูปแบบไฟล์

ตัวเลือก -f (จาก) และ -t (เป็น) ใช้เพื่อบอก pandoc ว่ารูปแบบไฟล์ใดที่คุณต้องการแปลงจากและไปเป็น ซึ่งจะมีประโยชน์หากคุณกำลังทำงานกับรูปแบบไฟล์ที่ใช้นามสกุลไฟล์ร่วมกับรูปแบบอื่นๆ ที่เกี่ยวข้อง ตัวอย่างเช่น TeX และ LaTeX ใช้นามสกุล ".tex"

เรายังใช้ตัวเลือก -s (สแตนด์อโลน) เพื่อให้ pandoc จะสร้างคำนำ LaTeX ทั้งหมดที่จำเป็นสำหรับเอกสารให้เป็นเอกสาร LaTeX ที่สมบูรณ์ มีในตัวเอง และมีรูปแบบที่ดี หากไม่มีตัวเลือก -s (สแตนด์อโลน) เอาต์พุตจะยังคงเป็น LaTeX ที่มีรูปแบบถูกต้อง ซึ่งสามารถเสียบเข้าไปในเอกสาร LaTeX อื่นได้ จะไม่สามารถแยกวิเคราะห์เป็นเอกสาร LaTeX แบบสแตนด์อโลนได้อย่างถูกต้อง

เราพิมพ์ดังต่อไปนี้:

 pandoc -f markdown -t latex -s -o sample.tex sample.md 

หากคุณเปิดไฟล์ “sample.tex” ในโปรแกรมแก้ไขข้อความ คุณจะเห็น LaTeX ที่สร้างขึ้น หากคุณมีโปรแกรมแก้ไข LaTeX คุณสามารถเปิดไฟล์ TEX เพื่อดูตัวอย่างวิธีตีความคำสั่งการเรียงพิมพ์ LaTeX ได้ การย่อหน้าต่างให้พอดีกับภาพด้านล่างทำให้จอแสดงผลดูแคบ แต่ในความเป็นจริง ถือว่าใช้ได้

เราใช้โปรแกรมแก้ไข LaTeX ชื่อ Texmaker หากคุณต้องการติดตั้งใน Ubuntu ให้พิมพ์ดังต่อไปนี้:

 sudo apt-get ติดตั้ง texmaker

ใน Fedora คำสั่งคือ:

 sudo dnf ติดตั้ง texmaker

ใน Manjaro ใช้:

 sudo pacman -Syu texmaker

การแปลงไฟล์ด้วยเทมเพลต

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

ด้วยเทมเพลต คุณสามารถกำหนดว่าสไตล์ใดที่ pandoc จะใช้ในการสร้างเอกสาร ตัวอย่างเช่น คุณสามารถบอกให้ pandoc ใช้สไตล์ที่กำหนดไว้ในไฟล์ Cascading Style Sheets (CSS) ด้วยตัวเลือก --css

เราได้สร้างไฟล์ CSS ขนาดเล็กที่มีข้อความด้านล่าง เปลี่ยนระยะห่างด้านบนและด้านล่างของส่วนหัวระดับหนึ่งสไตล์ นอกจากนี้ยังเปลี่ยนสีข้อความเป็นสีขาว และสีพื้นหลังเป็นเฉดสีฟ้า:

 ชั่วโมง1 {
  สี: #FFFFFF;
  สีพื้นหลัง: #3C33FF;
  ขอบบน: 0px;
  ระยะขอบล่าง: 1px;
}

คำสั่งแบบเต็มอยู่ด้านล่าง—โปรดทราบว่าเรายังใช้ตัวเลือกแบบสแตนด์อโลน ( -s ):

 pandoc -o sample.html -s --css sample.css sample.md

pandoc ใช้สไตล์เดียวจากไฟล์ CSS ที่เรียบง่ายและนำไปใช้กับส่วนหัวระดับหนึ่ง

ตัวเลือกการปรับแต่งอื่นที่คุณมีเมื่อทำงานกับไฟล์ HTML คือการรวมมาร์กอัป HTML ไว้ในไฟล์ Markdown ของคุณ สิ่งนี้จะถูกส่งผ่านไปยังไฟล์ HTML ที่สร้างขึ้นเป็นมาร์กอัป HTML มาตรฐาน

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

เราสามารถระบุรูปแบบที่จะใช้เมื่อสร้างไฟล์ ODT ได้เช่นกัน เปิดเอกสาร LibreOffice Writer เปล่า แล้วปรับรูปแบบหัวเรื่องและฟอนต์ให้เหมาะกับความต้องการของคุณ ในตัวอย่างของเรา เรายังเพิ่มส่วนหัวและส่วนท้ายด้วย บันทึกเอกสารของคุณเป็น “odt-template.odt”

ตอนนี้เราสามารถใช้สิ่งนี้เป็นเทมเพลตด้วยตัวเลือก --reference-doc :

 pandoc -o sample.odt --reference-doc=odt-template.odt sample.md 

เปรียบเทียบสิ่งนี้กับตัวอย่าง ODT จากก่อนหน้านี้ เอกสารนี้ใช้แบบอักษรอื่น มีหัวเรื่องเป็นสี และมีส่วนหัวและส่วนท้าย อย่างไรก็ตาม มันถูกสร้างขึ้นจากไฟล์ Markdown “sample.md” ที่เหมือนกันทุกประการ

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

กำลังสร้าง PDFs

ตามค่าเริ่มต้น pandoc ใช้เครื่องมือ LaTeX PDF เพื่อสร้างไฟล์ PDF วิธีที่ง่ายที่สุดในการตรวจสอบให้แน่ใจว่าคุณมีการพึ่งพา LaTeX ที่เหมาะสมคือการติดตั้งตัวแก้ไข LaTeX เช่น Texmaker

นั่นเป็นการติดตั้งที่ค่อนข้างใหญ่ แม้ว่า Tex และ LaTeX ต่างก็ค่อนข้างแข็งแกร่ง หากพื้นที่ฮาร์ดไดรฟ์ของคุณมีจำกัด หรือคุณรู้ว่าคุณจะไม่ใช้ TeX หรือ LaTeX เลย คุณอาจต้องการสร้างไฟล์ ODT จากนั้น คุณสามารถเปิดใน LibreOffice Writer และบันทึกเป็น PDF ได้

Docs-as-Code

มีข้อดีหลายประการในการใช้ Markdown เป็นภาษาเขียนของคุณ รวมถึงสิ่งต่อไปนี้:

• การทำงานในไฟล์ข้อความธรรมดานั้นรวดเร็ว: ไฟล์เหล่านี้ โหลดได้เร็วกว่าไฟล์เวิร์ดโปรเซสเซอร์ที่มีขนาดใกล้เคียงกัน และมีแนวโน้มที่จะเคลื่อนผ่านเอกสารได้เร็วกว่าด้วย บรรณาธิการหลายคน รวมถึง gedit , Vim และ Emacs ใช้การเน้นไวยากรณ์ด้วยข้อความ Markdown
• คุณจะมีไทม์ไลน์ของเอกสารทุกเวอร์ชัน: หากคุณจัดเก็บเอกสารของคุณใน VCS เช่น Git คุณจะเห็นความแตกต่างระหว่างไฟล์เดียวกันสองเวอร์ชันได้อย่างง่ายดาย อย่างไรก็ตาม สิ่งนี้ใช้ได้จริงเฉพาะเมื่อไฟล์เป็นข้อความธรรมดาเท่านั้น เนื่องจากนั่นคือสิ่งที่ VCS คาดว่าจะใช้งานได้
• VCS สามารถบันทึกว่าใครเป็นผู้ทำการเปลี่ยนแปลง และเมื่อใด: ซึ่งจะเป็นประโยชน์อย่างยิ่งหากคุณมักทำงานร่วมกับผู้อื่นในโครงการขนาดใหญ่ นอกจากนี้ยังมีพื้นที่เก็บข้อมูลส่วนกลางสำหรับเอกสารด้วย บริการ Git ที่โฮสต์บนคลาวด์มากมาย เช่น GitHub, GitLab และ BitBucket มีระดับฟรีในแบบจำลองการกำหนดราคา
• คุณสามารถสร้างเอกสารของคุณได้หลายรูปแบบ: ด้วยเชลล์สคริปต์ง่ายๆ เพียงไม่กี่ตัว คุณสามารถดึงสไตล์จาก CSS และเอกสารอ้างอิงได้ หากคุณจัดเก็บเอกสารของคุณไว้ในที่เก็บ VCS ที่ผสานรวมกับแพลตฟอร์มการบูรณาการอย่างต่อเนื่องและการปรับใช้อย่างต่อเนื่อง (CI/CD) เอกสารเหล่านี้จะถูกสร้างขึ้นโดยอัตโนมัติทุกครั้งที่มีการสร้างซอฟต์แวร์

ที่เกี่ยวข้อง: GitHub คืออะไรและใช้สำหรับอะไร?

ความคิดสุดท้าย

มีตัวเลือกและคุณลักษณะมากมายภายใน pandoc มากกว่าที่เรากล่าวถึงที่นี่ กระบวนการแปลงไฟล์ประเภทต่างๆ ส่วนใหญ่สามารถปรับเปลี่ยนและปรับแต่งได้ หากต้องการเรียนรู้เพิ่มเติม โปรดดูตัวอย่างที่ยอดเยี่ยมบนหน้าเว็บ pandoc อย่างเป็นทางการ (และมีรายละเอียดมาก)