github flavored markdown to html
1.0.0
Python-module ที่ใช้งานง่ายและแนวหน้าบรรทัดคำสั่งเพื่อแปลง Markdown เป็น HTML มันใช้ gitHubs ออนไลน์ markdown-to-html-API โดยค่าเริ่มต้น (ซึ่งต้องใช้การเชื่อมต่ออินเทอร์เน็ต) แต่มาพร้อมกับตัวเลือกสำหรับการแปลงออฟไลน์ (ซึ่งจะเลียนแบบพฤติกรรม GitHubs อย่างใกล้ชิด) และเครื่องมือ Python- หรือ Commandline อื่น ๆ สิ่งที่คุณใช้กับมันจะขยายออกไปโดยอัตโนมัติด้วยฟังก์ชั่นมากมายเช่นตัวเลือกในและเอาต์พุตมากขึ้น, CSS ที่มีรสชาติของ GitHub, การสนับสนุนสูตร, การแคชอิมเมจขั้นสูงและการเพิ่มประสิทธิภาพ, การจัดวางไฟล์และภาพโฮสต์และภาพ, pdf-conversion, การสนับสนุนรหัส
ในขณะที่วัตถุประสงค์หลักของมันคือการสร้างหน้าคงที่จากไฟล์ Markdown เช่นร่วมกับผู้สร้างเว็บไซต์แบบคงที่หรือการกระทำของ GitHub หากคุณโฮสต์บน GitHub มันสามารถใช้งานได้ดีสำหรับวัตถุประสงค์อื่น ๆ
นี่คือรายการข้อดีและคุณสมบัติ (ไม่จำเป็นต้องครอบคลุม) (
$ -formula- $ เพื่อใช้) ซึ่งมักจะไม่ได้ GH-MD-to-HTML ใช้ LaTeX และ DVISVGM หากทั้งคู่ติดตั้ง (ได้เปรียบ: เร็วไม่จำเป็นต้องใช้อินเทอร์เน็ต) และมิฉะนั้น Codecogs Eqneditor (ข้อได้เปรียบ: ไม่ต้องการให้คุณติดตั้งไลบรารี LaTex 3 GB) เพื่อให้ได้สิ่งนี้[[_TOC_]] , {:toc} และ [toc] ที่จุดเริ่มต้นของบรรทัดที่ว่างเปล่าเป็นอย่างอื่นเพื่อสร้างเนื้อหาของเนื้อหาสำหรับเอกสารเช่น markdown ที่มีรสชาติของ Gitlabในกรณีที่คุณกำลังมองหาทางเลือกแทน Pandoc สำหรับการแปลง Markdown เป็น PDF นี่คือรายการของเหตุผลที่คุณต้องการใช้ GH-MD-to-HTML แทน Pandoc สำหรับงาน:
ในขณะที่ใช้ Pandoc เพื่อแปลงจาก markdown เป็น PDF มักจะให้ผลลัพธ์ที่สวยงามมากขึ้น (Pandoc ใช้ Latex หลังจากทั้งหมด) GH-MD-to-HTML มีชุดของข้อได้เปรียบของตัวเองเมื่อมันมาถึงการแปลงไฟล์ที่ซับซ้อนสำหรับการบ้านหรือวัตถุประสงค์อื่น ๆ
$ -Signs และตัวละครที่สูตรอาจเริ่มต้นด้วย กฎเหล่านี้ไม่ได้ใช้ในตัวแก้ไข Markdown ทั่วไปเช่น Marktext ซึ่งนำไปสู่ความยุ่งยากมากมายเมื่อสูตรที่ทำงานในตัวแก้ไขไม่ทำงานอีกต่อไปเมื่อแปลงด้วย Pandoc (บางครั้งการส่งออกไปยัง PDF-PDF ของตัวเองก็ล้มเหลวในไฟล์สูตรหนักโดยไม่มีข้อความแสดงข้อผิดพลาด ส่วนที่แย่ที่สุดคือเมื่อใดก็ตามที่ Pandoc ล้มเหลวในการแปลง. md เป็น. pdf ด้วยเหตุนี้จะแสดงจำนวนบรรทัดของข้อผิดพลาดตามตัวกลาง. tex-file แทนที่จะเป็นอินพุต. md-file ซึ่งทำให้ยากต่อการหารูทปัญหา อย่างที่คุณอาจเดาได้ GH-MD-to-HTML ไม่สามารถสนใจได้น้อยลงเกี่ยวกับปริมาณของช่องว่างที่คุณเริ่มต้นสูตรของคุณด้วยการตัดสินใจนี้ขึ้นอยู่กับคุณโดยสรุปแล้ว MD-to-PDF-conversion ของ Pandoc ทำหน้าที่ค่อนข้างผิดปกติเมื่อพูดถึงภาพรายการซ้อนกันรายการ Bullet Point Multiline หรือสูตรและ GH-MD-to-HTML ไม่ได้
ใช้ pip3 install gh-md-to-html เพื่อติดตั้งโดยตรงจากดัชนีแพ็คเกจ Python หรือ python3 -m pip install gh-md-to-html หากคุณอยู่บน Windows
ทั้งสองอาจต้องใช้ sudo บน Linux และคุณสามารถเลือกได้
python3 -m pip install gh-md-to-html[pdf_export]
และติดตั้ง wkhtmltopdf (v0.12.6 หรือมากกว่า) เพื่อรับคุณสมบัติ PDF-conversion เสริมและแปลงไฟล์ markdown เป็น PDF และ/หรือ
python3 -m pip install gh-md-to-html[offline_conversion]
เพื่อให้ได้คุณสมบัติการแปลงแบบออฟไลน์เสริมและทำงาน
หากคุณอยู่บน Windows คุณอาจต้องเพิ่ม wkhtmltopdf ลงในเส้นทางของคุณในไดเรกทอรีการทำงานปัจจุบันของคุณเพื่อให้ได้การแปลง PDF เป็นงานเช่น PATH=%PATH%;c:/program files/wkhtmltopdf/bin หรือสิ่งที่คล้ายกันขึ้นอยู่กับตำแหน่งการติดตั้งของคุณ
หากคุณต้องการเข้าถึงอินเทอร์เฟซด้วยบรรทัดคำสั่งของคุณคุณสามารถจัดหา gh-md-to-html พร้อมอาร์กิวเมนต์ที่บันทึกไว้ในข้อความช่วยเหลือ (เข้าถึงได้ด้วย gh-md-to-html -h และแสดงด้านล่าง) บน Windows คุณต้องจัดหา python3 -m gh_md_to_html พร้อมอาร์กิวเมนต์ที่เกี่ยวข้อง
หากคุณต้องการเข้าถึงอินเทอร์เฟซผ่าน Python คุณสามารถใช้งานได้
import gh_md_to_html จากนั้นใช้ gh_md_to_html.main() ด้วยอาร์กิวเมนต์เดียวกัน (และค่าเริ่มต้น) คุณจะส่งไปยังอินเทอร์เฟซบรรทัดคำสั่ง
หากคุณต้องการเลียนแบบผลการแปลงโดย REST API ของ GitHub แต่ไม่ต้องการการแคชรูปภาพการสนับสนุนสูตรและสไตล์ CSS แฟนซีใช้
html_as_a_string = gh_md_to_html.core_converter.markdown(your_markdown_as_a_string)
ใน Python
การใช้งาน : gh-md-to-html <input_name> <optional_arguments>
พฤติกรรมเริ่มต้น :
โดยค่าเริ่มต้น GH-MD-to-HTML ใช้ชื่อไฟล์ markdown เป็นอาร์กิวเมนต์และบันทึก HTML ที่สร้างขึ้นในไฟล์ที่มีชื่อเดียวกันด้วย .html แทน .md
บางนิสัยแปลก:
github-markdown-css/github-css.css (Add -c เพื่อให้อินไลน์แทน)./images (เพิ่ม -i เพื่อปิดการใช้งานสิ่งนี้)-w หากคุณต้องการดูโดยตรงในเบราว์เซอร์แทน)id S และไฟล์ภายในทั้งหมดจะถูกนำไปใช้โดย user-content- ดังนั้นคุณสามารถฝัง HTML ที่สร้างขึ้นในเว็บไซต์ที่ใหญ่กว่าโดยไม่เสี่ยงกับการปะทะกันของ ID กรณีการใช้งานทั่วไปบางกรณี :
จากปัญหาที่ผ่านมาฉันรู้ว่ามีบางกรณีการใช้งานทั่วไปที่คนส่วนใหญ่ดูเหมือนจะมีสำหรับโมดูลนี้ นี่คือตัวเลือกที่พบบ่อยที่สุดและตัวเลือกและอาร์กิวเมนต์ที่จะใช้สำหรับพวกเขา:
-i -w --math false --box-width 25cm แม้ว่าการจับอาจมีประสิทธิภาพมากขึ้นสำหรับจุดประสงค์นี้--toc เพื่อรองรับไวยากรณ์ TOC ของ Gitlab--math true --emoji-support 0 --dont-make-images-links true-i -c เพื่อให้มีทุกอย่างในไฟล์เดียว การแปลงไฟล์ Markdown จากเว็บ ด้วย --origin-type :
คุณอาจไม่เพียง แต่แปลงไฟล์ Markdown ในเครื่องเท่านั้น แต่ยังรวมถึงไฟล์จากที่เก็บ GitHub, เว็บโฮสต์หรือเนื้อหาของสตริง เพียงดาวน์โหลดสิ่งเหล่านี้หรือจัดเก็บไว้ในไฟล์มักจะไม่เพียงพอเนื่องจากตำแหน่งของพวกเขาบนเว็บยังมีผลต่อวิธีการเชื่อมโยงไปยังรูปภาพที่พวกเขาอ้างอิงจะต้องได้รับการแก้ไข โชคดีที่ GH-MD-to-HTML ได้รับกลับมาแล้ว!
มีอาร์กิวเมนต์ต่าง ๆ จำนวนมากที่คุณสามารถใช้เพื่ออธิบายประเภทของไฟล์ที่คุณให้การอ้างอิง:
--origin-type file : ค่าเริ่มต้น; ใช้เส้นทางไฟล์ (สัมพัทธ์หรือสัมบูรณ์)--origin-type repo : ใช้ pth ไปยังไฟล์ markdown ในที่เก็บ github ในรูปแบบ <user_name>/<repo_name>/<branch-name>/<path_to_markdown>.md <branch-name>/<path_to_markdown> .md--origin-type web : ใช้ URL ของไฟล์ Markdown ที่โฮสต์เว็บ--origin-type string : ใช้สตริงที่มี markdown ตัวเลือกเหล่านี้บางอย่างที่คุณใช้อิทธิพลของการเชื่อมโยงรูปภาพภายในไฟล์ Markdown ได้รับการแก้ไข ส่วนต่อมาของ readme นี้แสดงรายละเอียดนี้ ปรับแต่งสิ่งที่ไปที่ไหน :
GH-MD-to-HTML เขียนโดยมีเป้าหมายในการสร้างเว็บไซต์คงที่พร้อมโฮสต์สำหรับคุณด้วยไดเรกทอรีการทำงานปัจจุบันของคุณเป็นรูท นอกเหนือจากการใช้ -w เพื่อปิดการใช้งานและอนุญาตให้คุณดูไฟล์ที่สร้างขึ้นโดยตรงในเบราว์เซอร์มีตัวเลือกมากมายที่ช่วยให้คุณปรับแต่งสิ่งที่ไปที่ไหนและที่นิยมมากที่สุดเปลี่ยนรูทของเว็บไซต์ ไม่จำเป็นต้องทำเช่นนั้นเว้นแต่คุณต้องการด้วยเหตุผลบางอย่างดังนั้นอย่ากังวลกับการอ่านสิ่งนี้หากคุณไม่ต้องการ!
--website-root (หรือ -w ): การปล่อยให้ตัวเลือกนี้ว่างเปล่าตามที่กล่าวไว้ข้างต้นช่วยให้คุณสามารถดูตัวอย่างไฟล์ HTML ที่สร้างขึ้นโดยตรงในเบราว์เซอร์ (ในระบบส่วนใหญ่โดยคลิกสองครั้ง) ในกรณีที่คุณไม่ต้องการโฮสต์ไฟล์ HTML ที่สร้างขึ้น แต่คุณยังสามารถจัดหาไดเรกทอรีใด ๆ ที่คุณต้องการใช้ เป็นค่าเริ่มต้นไปยังไดเรกทอรีการทำงานปัจจุบันของคุณ--destination (หรือ -d ): เส้นทางที่สัมพันธ์กับ --website-root ซึ่งเก็บไฟล์ HTML ที่สร้างขึ้นไว้ โดยค่าเริ่มต้นรูทเว็บไซต์จะใช้สำหรับสิ่งนี้--image-paths (หรือ -i ): คุณสามารถปล่อยให้ว่างเปล่านี้เพื่อปิดการแคชภาพดังที่อธิบายไว้ข้างต้น (แม้ว่าจะไม่ได้ผลในกรณีที่คุณแก้ไข --origin-type ) หรือจัดหาเส้นทางที่สัมพันธ์กับการรูตเว็บไซต์เพื่อแก้ไขตำแหน่งที่จัดเก็บ มันเริ่มต้นเป็น imagesimage-paths ไดเรกทอรีไม่ได้ถูกปล่อยโดยอัตโนมัติระหว่างการรันหลายครั้งของ GH-MD-to-HTML ด้วยเหตุผลนี้เพื่อให้แน่ใจว่าการเพิ่มประสิทธิภาพนี้สามารถใช้ไฟล์ข้ามได้เมื่อแปลงหลายไฟล์เป็นกลุ่ม--css-paths (หรือ -c ): คุณสามารถปล่อยให้ว่างเปล่านี้เพื่อปิดการจัดเก็บ CSS ในไฟล์ CSS github-css.css (มีประโยชน์เช่นหากคุณต้องการแปลงไฟล์เดียวเท่านั้น) ตามที่อธิบายไว้ข้างต้น ค่าเริ่มต้นคือ github-markdown-css--output-name (หรือ -n ): ชื่อไฟล์ที่จะจัดเก็บไฟล์ HTML ที่สร้างขึ้นในไดเรกทอรีปลายทาง คุณสามารถใช้ <name> ที่ใดก็ได้ในสตริงนี้และมันจะถูกแทนที่โดยอัตโนมัติด้วยชื่อของ --origin-type string ดังนั้นตัวอย่างเช่น gh-md-to-html inp.md -n "<name>-conv.html" จะเก็บผลลัพธ์ไว้ใน ino-conv.html-n print เพื่อเขียนเอาต์พุตไปยัง stdout (พิมพ์บนคอนโซล) แทนที่จะบันทึกได้ทุกที่ ค่าเริ่มต้นคือ <name>.html ดังนั้นจึงปรับให้เข้ากับชื่อไฟล์อินพุตของคุณ--output-pdf (หรือ -p ): ไฟล์ที่จะจัดเก็บ PDF ที่สร้างขึ้น คุณสามารถใช้ <name> -syntax ได้ที่นี่เช่นกัน หากไม่ได้ใช้ -p -OPTION จะไม่มีการสร้าง PDF (และคุณจำเป็นต้องทำตามคำแนะนำการติดตั้ง PDFKIT & <name>.pdf ด้านบนเพื่อให้ตัวเลือกนี้ใช้งานได้) แต่คุณสามารถใช้ -p ได้โดยไม่ต้องมีอาร์กิวเมนต์ใด ๆ การส่งออกเป็น PDF :
ดังที่ได้กล่าวมาแล้วคุณสามารถส่งออกไฟล์ HTML ที่สร้างขึ้นเป็น PDF โดยใช้ --output-pdf -OPTION การทำเช่นนั้นคุณจะต้องติดตั้ง wkhtmltopdf (เวอร์ชัน QT-patched) เพื่อเพิ่มลงในเส้นทาง (ถ้าคุณอยู่บน Windows) และติดตั้ง pdfkit (เช่นผ่าน pip3 install gh-md-to-html[offline_conversion] )
แม้ว่าจะมีบางสิ่งที่น่าสังเกตที่นี่ ก่อนอื่นอย่าใช้ตัวเลือกนี้หากคุณมีข้อมูลที่มีค่าในไฟล์ที่เรียกว่า {yourpdfexportdestination}.html โดยที่ {yourpdfexportdestination} เป็นสิ่งที่คุณจัดหาให้ -p เนื่องจากไฟล์นี้จะถูกเขียนทับชั่วคราวในกระบวนการ; นอกจากนี้อย่าใช้ -p เลยหากคุณกำลังจัดหาอินพุตที่ไม่น่าเชื่อถือให้กับ -x -OPTION
นอกจากนี้ยังมีตัวเลือกบางอย่างที่ปรับแต่งโดยเฉพาะสำหรับใช้กับ -p ; นี่คือปัจจุบัน:
--style-pdf (หรือ -s ): ตั้งค่าเป็น false เพื่อปิดการใช้งานสไตล์ไฟล์ PDF ที่สร้างขึ้นด้วย CSS ของ GitHub คุณอาจต้องการทำสิ่งนี้เพราะเส้นขอบที่ CSS ของ GitHub ดึงรอบหน้าสามารถดูได้ง่ายใน PDFs แม้ว่าการทำเช่นนั้นอาจมีอิทธิพลในทางลบต่อการปรากฏตัวของชิ้นส่วนอื่น ๆ ดังนั้นใช้กับเม็ดเกลือ การเปลี่ยนตัวแปลง Markdown หลักที่จะใช้ :
GH-MD-to-HTML ไม่ได้ทำทุกอย่างที่หนักมากเมื่อพูดถึงการแยกวิเคราะห์การทำเครื่องหมายและแปลงเป็น PDF แต่มันจะล้อมรอบ "ตัวแปลงหลัก" ที่เรียกว่าการแปลงขั้นพื้นฐานตามสเป็ค markdown และสร้างตัวเลือกคุณสมบัติการปรับแต่งและการออกแบบของตัวเอง โดยค่าเริ่มต้น GitHub Markdown REST API นั้นใช้สำหรับสิ่งนั้นเนื่องจากใกล้เคียงกับสิ่งที่ GitHub ทำกับ readmes แต่คุณยังสามารถให้ GH-MD-to-HTML ตัวแปลง Markdown พื้นฐานอื่น ๆ เพื่อทำงานด้วย
GH-MD-to-HTML ยังมาพร้อมกับตัวแปลงหลักทางเลือกในการสร้างสองตัวเพื่อใช้ซึ่งเลียนแบบ REST API ของ GitHub ให้ใกล้เคียงที่สุดเท่าที่จะเป็นไปได้ในขณะที่เพิ่มสัมผัสส่วนตัวของพวกเขาเอง
ตัวเลือกในการตัดสินใจตัวแปลงหลัก:
--core-converter (หรือ -o ): คุณสามารถใช้ตัวเลือกนี้เพื่อเลือกจากตัวแปลงหลักที่กำหนดไว้ล่วงหน้าจำนวนหนึ่ง (ดูด้านล่าง) ในกรณีที่คุณต้องการแตกต่างจากค่าเริ่มต้น
นอกจากนี้คุณยังสามารถจัดหาคำสั่ง BASH (บนระบบ UNIX/LINUX) ไปยังสิ่งนี้หรือคำสั่ง cmd.exe บน Windows ซึ่ง {md} ยืนเป็นตัวยึดตำแหน่งที่การทำเครื่องหมายอินพุตแบบเชลล์จะถูกแทรกโดย GH-MD-to-HTML ตัวอย่างเช่น,
gh-md-to-html inp.md -o "pandoc -f markdown -t html <<< {md}"
จะใช้ Pandoc เป็นตัวแปลงหลัก
คุณสามารถทำได้โดยใช้หลายคำสั่งเช่น
gh-md-to-html -o "printf {md} >> temp.md; pandoc -f markdown -t html temp.md; rm temp.md" ,
ตราบใดที่ผลลัพธ์ถูกพิมพ์ไปยัง stdout
หากคุณใช้ Python-Interface เป็น GH-MD-to-HTML คุณยังสามารถจัดหาฟังก์ชั่นใด ๆ ที่แปลงสตริง markdown เป็นสตริง HTML เป็นอาร์กิวเมนต์นี้
ตัวแปลงหลักที่กำหนดไว้ล่วงหน้าซึ่งคุณสามารถจัดหาได้อย่างง่ายดาย --core-converter เป็นสตริง:
OFFLINE : เลียนแบบ Markdown REST ของ GitHub แต่ออฟไลน์โดยใช้ Mistune สิ่งนี้ต้องการการพึ่งพาตัวเลือกสำหรับ "Offline_Conversion" เพื่อให้ได้รับความพึงพอใจโดยใช้ pip3 install gh-md-to-html[offline_conversion] หรือ pip3 install mistune>=2.0.0rc1OFFLINE+ : ทำงานเหมือนกันกับออฟไลน์ แต่ไม่ได้ลบเนื้อหาที่อาจเป็นอันตรายเช่น JavaScript และ CSS เช่น GitHub REST API มักจะทำ อย่าใช้คุณสมบัตินี้เว้นแต่คุณจะต้องมีวิธีในการแปลงไฟล์ Markdown ที่ตรวจสอบด้วยตนเองอย่างปลอดภัยโดยไม่ต้องมีการจัดแต่งทรงผมแบบอินไลน์ทั้งหมดของคุณ! สนับสนุน Inline-Formulas :
gh-md-to-html รองรับสูตรแบบอินไลน์ (ไม่ว่าตัวแปลงหลักใดให้ดูด้านบนคุณใช้) ซึ่งหมายความว่าคุณสามารถเขียนสูตรน้ำยางระหว่างสัญญาณสองดอลลาร์ในบรรทัดเดียวกันและจะถูกแทนที่ด้วยภาพ SVG ที่แสดงสูตรดังกล่าว ตัวอย่างเช่น,
$e = m cdot c^2$
จะเพิ่มสูตรที่มีชื่อเสียงของ Einstein เป็นภาพ SVG ซึ่งสอดคล้องกับข้อความที่เหลืออยู่รอบ ๆ ในเอกสารของคุณ
gh-md-to-html พยายามใช้การติดตั้ง LaTex ในพื้นที่ของคุณเสมอเพื่อทำการแปลงนี้ (ความได้เปรียบ: เร็วและไม่ต้องใช้อินเทอร์เน็ต) อย่างไรก็ตามหากไม่ได้ติดตั้ง LaTeX หรือ DVISVGM หรือไม่พบพวกเขาจะใช้ตัวแปลงออนไลน์ (ข้อดี: ไม่ต้องการให้คุณติดตั้งไลบรารี LaTex 3 GB) เพื่อให้ได้สิ่งนี้
คุณสามารถใช้ตัวเลือกต่อไปนี้เพื่อแก้ไขพฤติกรรมนี้:
--math (หรือ -m ): ตั้งค่าเป็น false เพื่อปิดใช้งานการแสดงผลสูตร--suppress-online-fallbacks : ตั้งค่านี้เป็น true เพื่อปิดการใช้งานทางเลือกออนไลน์สำหรับการแสดงผลสูตรการเพิ่มข้อผิดพลาดหากข้อกำหนดของมันไม่ได้ติดตั้งในพื้นที่หรือไม่สามารถพบได้ด้วยเหตุผลบางอย่าง การแคชรูปภาพและการบีบอัดภาพ :
ตามที่อธิบายไว้ในเชิงลึกด้านบน GH-MD-to-HTML จะบันทึกภาพเพื่อให้พวกเขาสามารถโหลดได้จากโฟลเดอร์เดียวกัน สิ่งนี้มาพร้อมกับข้อดีของ
นอกเหนือจากข้อดีเหล่านี้ GH-MD-to-HTML ยังช่วยให้คุณสามารถตั้งค่าระดับการบีบอัดภาพเพื่อใช้สำหรับภาพเหล่านี้ หากคุณตัดสินใจที่จะทำเช่นนั้นภาพทุกภาพจะถูกแปลงเป็น JPEG (โดยใช้สี width หลังและการตั้งค่า height ตามความชอบของคุณ) และภาพจะถูกลดขนาดหาก HTML <img> สร้างขึ้นระบุว่าพวกเขาจะไม่ต้องการขนาดเต็ม (คุณสามารถใช้ประโยชน์จากค่านี้ได้
GH-MD-to-HTML ยังเป็นตัวแปลง Markdown เพียงตัวเดียวที่สามารถใช้ประโยชน์จาก HTML srcset -Attribute ซึ่งช่วยให้เอกสารที่สร้างขึ้นสามารถอ้างอิงภาพที่มีขนาดต่างกันหลายรุ่นที่แตกต่างกันซึ่งเบราว์เซอร์จะโหลดขนาดใหญ่ที่มีขนาดเล็กที่สุด การเปิดใช้งานคุณสมบัตินี้สามารถนำไปสู่การลดเวลาในการโหลดเพิ่มเติมโดยไม่ต้องเสียสละคุณภาพของภาพที่มองเห็นได้ซึ่งทำให้ GH-MD-to-HTML เป็นตัวเลือกที่ดีที่สุดหากคุณต้องการสร้างเว็บไซต์ที่โหลดเร็วจากไฟล์มาร์เดอร์ที่หนักหน่วงของภาพ
ตัวเลือกที่จะใช้สำหรับทั้งหมดนี้คือ
--compress-images
และยอมรับข้อมูลชิ้นส่วนของ JSON ที่มีคุณลักษณะดังต่อไปนี้:
bg-color : สีที่ใช้เป็นสีพื้นหลังเมื่อแปลง RGBA-Images เป็น JPEG (รูปแบบ RGB) ค่าเริ่มต้นเป็น " white " และยอมรับค่าสี HTML5 เกือบทุกสี (" #FFFFFF ", " #ffffff ", " white " และ " rgb(255, 255, 255) " ทั้งหมดจะเป็นค่าที่ถูกต้อง)progressive : บันทึกภาพเป็น JPEG แบบก้าวหน้า ค่าเริ่มต้นเป็นเท็จsrcset : บันทึกภาพเวอร์ชันที่ปรับขนาดต่างกันและให้ภาพเหล่านั้นกับภาพในแอตทริบิวต์ SRCSET ค่าเริ่มต้นเป็นเท็จ ใช้ความกว้างที่แตกต่างกันหรือ True ซึ่งทำหน้าที่เป็นทางลัดสำหรับ " [500, 800, 1200, 1500, 1800, 2000] "quality : ค่าจาก 0 ถึง 100 อธิบายว่าควรบันทึกภาพคุณภาพที่ควรบันทึกไว้ ค่าเริ่มต้นเป็น 90 หากมีการระบุขนาดเฉพาะสำหรับภาพเฉพาะใน HTML ภาพจะถูกแปลงเป็นขนาดที่เหมาะสมเสมอ ก่อนที่ จะลดคุณภาพหากอาร์กิวเมนต์นี้ว่างเปล่าจะไม่ใช้การบีบอัดเลย หากอาร์กิวเมนต์นี้ถูกตั้งค่าเป็นจริงจะใช้ค่าเริ่มต้นทั้งหมด หากตั้งค่าเป็นข้อมูล JSON และค่าบางส่วนจะถูกละเว้นค่าเริ่มต้นจะใช้สำหรับสิ่งเหล่านี้
นอกจากนี้คุณยังสามารถผ่าน dict แทนสตริงที่มีข้อมูล JSON หากคุณใช้ตัวเลือกนี้ในส่วนหน้า Python
การบีบอัดภาพจะไม่ทำงานด้วยเหตุผลที่ชัดเจนหากคุณใช้ -i เพื่อปิดการใช้งานการแคชภาพ
ตัวเลือกส่วนตัวของฉัน :
markdown และ markdown ที่มีรสชาติของ GitHub โดยทั่วไปทำให้ตัวเลือกที่ไม่เป็นที่นิยมและ GH-MD-to-HTML เลียนแบบมันทำให้สิ่งเหล่านี้เป็นจำนวนมาก หากเป้าหมายของคุณไม่ใกล้เคียงที่สุดเท่าที่จะเป็นไปได้ที่จะทำเครื่องหมาย (GitHub-flavored) และคุณต้องการใช้พลังเต็มรูปแบบที่ GH-MD-to-HTML เสนอให้เต็มที่ฉันขอแนะนำรายการการตั้งค่าและตัวเลือกที่มีความคิดเห็นต่อไปนี้ โปรดทราบว่าสิ่งเหล่านี้บางอย่างไม่ปลอดภัยเมื่อแปลงเนื้อหาที่ผู้ใช้สร้างขึ้น
--math true : สิ่งนี้เปิดใช้งานแล้วโดยค่าเริ่มต้นดังนั้นจึงไม่ใช่คำแนะนำจริงๆ แต่คุณมักจะต้องการการสนับสนุนทางคณิตศาสตร์ LaTex ในไฟล์ของคุณ--core-converter OFFLINE+ : สิ่งนี้จะแปลงไฟล์มาร์กดาวน์ออฟไลน์แทนการใช้ REST API ของ GitHub และอนุญาตให้ใช้สิ่งที่ไม่ปลอดภัยเช่นรหัสอินไลน์และ HTML ทุกตัวที่คุณต้องการในไฟล์ markdown ของคุณ--compress-images : มีหลายวิธีในการปรับให้เลือกตัวเลือกนี้ แต่ช่วยให้การปรับให้เหมาะสมที่สุดในภาพที่แคชรวมถึงการใช้ HTML srcset -Attribute ซึ่งไม่มีตัวแปลง Markdown อื่น ๆ รองรับ AFAIK--box-width 25cm : คุณมักจะต้องการ จำกัด ความกว้างของกล่องที่เนื้อหาของเว็บไซต์ที่สร้างขึ้นจะแสดงด้วยเหตุผลของการอ่านเว้นแต่คุณจะวางแผนที่จะฝัง HTML ที่สร้างขึ้นไว้ในไฟล์ HTML ที่ใหญ่กว่า--toc true : สิ่งนี้ช่วยให้คุณใช้ [[_TOC_]] เป็นทางลัดสำหรับสารบัญในไฟล์ที่สร้างขึ้น--dont-make-images-links true : โดยค่าเริ่มต้น GitHub จะห่อทุกภาพลงในลิงก์ไปยังแหล่งที่มาของภาพเว้นแต่ว่าภาพจะถูกห่อไว้ในลิงค์อื่นแล้ว ตัวเลือกนี้ปิดใช้งานพฤติกรรมนี้เพื่อควบคุมลิงก์ของรูปภาพของคุณมากขึ้น--emoji-support 2 : GH-MD-to-HTML รองรับการใช้รหัสย่อของอิโมจิเช่น :joy: ซึ่งจะถูกแทนที่ด้วยอิโมจิในไฟล์ HTML ที่สร้างขึ้น --emoji-support 2 ใช้ระดับนี้ต่อไปโดยอนุญาตให้คุณใช้อีโมจิที่กำหนดเองของคุณเองดังนั้น :path/to/funny_image.png: จะเพิ่ม funny_image.png เป็นอิโมจิขนาดอิโมจิลงในข้อความ--soft-wrap-in-code-boxes true : โดยค่าเริ่มต้น GitHub จะแสดงกล่องรหัส multiline ด้วยแถบเลื่อนแนวนอนหากพวกเขาเสี่ยงต่อการไหลล้น ใช้ตัวเลือกนี้เพื่อให้ (IMHO มีความสมเหตุสมผลมากขึ้น) soft-wrap ในกล่องรหัสแทน โปรดทราบว่าตัวเลือกมีการจัดเรียงตามความเกี่ยวข้องและทั้งหมดมีค่าเริ่มต้นที่สมเหตุสมผลดังนั้นอย่ารู้สึกท่วมท้นกับจำนวนที่มี; คุณสามารถอ่านผ่านพวกเขาจนกว่าคุณจะพบสิ่งที่คุณกำลังมองหาและไม่สนใจส่วนที่เหลืออย่างปลอดภัย
ตัวเลือกส่วนใหญ่มีไว้เพื่อปรับแต่งพฤติกรรมเริ่มต้นดังนั้นจึงไม่มีสิ่งใดที่จำเป็นสำหรับกรณีการใช้งานส่วนใหญ่
usage: __main__.py [-h] [-t {file,repo,web,string}]
[-w WEBSITE_ROOT [WEBSITE_ROOT ...]]
[-d DESTINATION [DESTINATION ...]]
[-i [IMAGE_PATHS [IMAGE_PATHS ...]]]
[-c CSS_PATHS [CSS_PATHS ...]]
[-n OUTPUT_NAME [OUTPUT_NAME ...]]
[-p OUTPUT_PDF [OUTPUT_PDF ...]] [-s STYLE_PDF]
[-f FOOTER [FOOTER ...]] [-m MATH]
[-x EXTRA_CSS [EXTRA_CSS ...]]
[-o CORE_CONVERTER [CORE_CONVERTER ...]]
[-e COMPRESS_IMAGES [COMPRESS_IMAGES ...]]
[-b BOX_WIDTH [BOX_WIDTH ...]] [-a TOC]
MD-origin [MD-origin ...]
Convert markdown to HTML using the GitHub API and some additional tweaks with
python.
positional arguments:
MD-origin Where to find the markdown file that should be
converted to html
optional arguments:
-h, --help show this help message and exit
-t {file,repo,web,string}, --origin-type {file,repo,web,string}
In what way the MD-origin-argument describes the origin
of the markdown file to use. Defaults to file. The
options mean:
* file: takes a relative or absolute path to a file
* repo: takes a path to a markdown-file in a github
repository, such as <user_name>/<repo_name>/<branch-
name>/<path_to_markdown>.md
* web: takes an url to a markdown file
* string: takes a string containing the files content
-w WEBSITE_ROOT [WEBSITE_ROOT ...], --website-root WEBSITE_ROOT [WEBSITE_ROOT ...]
Only relevant if you are creating the html for a static
website which you manage using git or something similar.
--website-root is the directory from which you serve
your website (which is needed to correctly generate the
links within the generated html, such as the link
pointing to the css, since they are all root- relative),
and can be a relative as well as an absolute path.
Defaults to the directory you called this script from.
If you intent to view the html file on your laptop
instead of hosting it on a static site, website-root
should be a dot and destination not set. The reason the
generated html files use root-relative links to embed
images is that on many static websites,
https://foo/bar/index.html can be accessed via
https://foo/bar, in which case relative (non-root-
relative) links in index.html will be interpreted as
relative to foo instead of bar, which can cause images
not to load.
-d DESTINATION [DESTINATION ...], --destination DESTINATION [DESTINATION ...]
Where to store the generated html. This path is relative
to --website-root. Defaults to "".
-i [IMAGE_PATHS [IMAGE_PATHS ...]], --image-paths [IMAGE_PATHS [IMAGE_PATHS ...]]
Where to store the images needed or generated for the
html. This path is relative to website-root. Defaults to
the "images"-folder within the destination folder. Leave
this option empty to completely disable image
caching/downloading and leave all image links
unmodified.
-c CSS_PATHS [CSS_PATHS ...], --css-paths CSS_PATHS [CSS_PATHS ...]
Where to store the css needed for the html (as a path
relative to the website root). Defaults to the
"<WEBSITE_ROOT>/github-markdown-css"-folder.
-n OUTPUT_NAME [OUTPUT_NAME ...], --output-name OUTPUT_NAME [OUTPUT_NAME ...]
What the generated html file should be called like. Use
<name> within the value to refer to the name of the
markdown file that is being converted (if you don't use
"-t string"). You can use '-n print' to print the file
(if using the command line interface) or return it (if
using the python module), both without saving it.
Default is '<name>.html'.
-p OUTPUT_PDF [OUTPUT_PDF ...], --output-pdf OUTPUT_PDF [OUTPUT_PDF ...]
If set, the file will also be saved as a pdf file in the
same directory as the html file, using pdfkit, a python
library which will also need to be installed for this to
work. You may use the <name> variable in this value like
you did in --output-name. Do not use this with the -c
option if the input of the -c option is not trusted;
execution of malicious code might be the consequence
otherwise!!
-s STYLE_PDF, --style-pdf STYLE_PDF
If set to false, the generated pdf (only relevant if you
use --output-pdf) will not be styled using github's css.
-f FOOTER [FOOTER ...], --footer FOOTER [FOOTER ...]
An optional piece of html which will be included as a
footer where the 'hosted with <3 by github'-footer in a
gist usually is. Defaults to None, meaning that the
section usually containing said footer will be omitted
altogether.
-m MATH, --math MATH If set to True, which is the default, LaTeX-formulas
using $formula$-notation will be rendered.
-x EXTRA_CSS [EXTRA_CSS ...], --extra-css EXTRA_CSS [EXTRA_CSS ...]
A path to a file containing additional css to embed into
the final html, as an absolute path or relative to the
working directory. This file should contain css between
two <style>-tags, so it is actually a html file, and can
contain javascript as well. It's worth mentioning and
might be useful for your css/js that every element of
the generated html is a child element of an element with
id xxx, where xxx is "article-" plus the filename
(without extension) of:
* output- name, if output-name is not "print" and not
the default value.
* the input markdown file, if output- name is "print",
and the input type is not string. * the file with the
extra-css otherwise. If none of these cases applies, no
id is given.
-o CORE_CONVERTER [CORE_CONVERTER ...], --core-converter CORE_CONVERTER [CORE_CONVERTER ...]
The converter to use to convert the given markdown to
html, before additional modifications such as formula
support and image downloading are applied; this defaults
to using GitHub's REST API and can be
* on Unix/ any system with a cmd: a command containing
the string "{md}", where "{md}" will be replaced with an
escaped version of the markdown file's content, and
which returns the finished html. Please note that
commands for Unix-system won't work on Windows systems,
and vice versa etc.
* when using gh-md-to- html in python: A callable which
converts markdown to html, or a string as described
above.
* OFFLINE as a value to indicate that gh-md-to-html
should imitate the output of their builtin
md-to-html-converter using mistune. This requires the
optional dependencies for "offline_conversion" to be
satisfied, by using `pip3 install
gh-md-to-html[offline_conversion]` or `pip3 install
mistune>=2.0.0rc1`.
* OFFLINE+ behaves identical to OFFLINE, but it doesn't
remove potentially harmful content like javascript and
css like the GitHub REST API usually does. DO NOT USE
THIS FEATURE unless you need a way to convert secure
manually-checked markdown files without having all your
inline js stripped away!
-e COMPRESS_IMAGES [COMPRESS_IMAGES ...], --compress-images COMPRESS_IMAGES [COMPRESS_IMAGES ...]
Reduces load time of the generated html by saving all
images referenced by the given markdown file as jpeg.
This argument takes a piece of json data containing the
following information; if it is not used, no compression
is done:
* bg-color: the color to use as a background color when
converting RGBA-images to jpeg (an RGB-format). Defaults
to "white" and accepts almost any HTML5 color-value
("#FFFFFF", "#ffffff", "white" and "rgb(255, 255, 255)"
would've all been valid values).
* progressive: Save images as progressive jpegs. Default
is False.
* srcset: Save differently scaled versions of the image
and provide them to the image in its srcset attribute.
Defaults to False. Takes an array of different widths or
True, which serves as a shortcut for "[500, 800, 1200,
1500, 1800, 2000]".
* quality: a value from 0 to 100 describing at which
quality the images should be saved (this is done after
they are scaled down, if they are scaled down at all).
Defaults to 90. If a specific size is specified for a
specific image in the html, the image is always
converted to the right size. If this argument is left
empty, no compression is down at all. If this argument
is set to True, all default values are used. If it is
set to json data and values are omitted, the defaults
are also used. If a dict is passed instead of json data
(when using the tool as a python module), the dict is
used as the result of the json data.
-b BOX_WIDTH [BOX_WIDTH ...], --box-width BOX_WIDTH [BOX_WIDTH ...]
The text of the rendered file is always displayed in a
box, like GitHub READMEs and issues are. By default,
this box fills the entire screen (max-width: 100%), but
you can use this option to reduce its max width to be
more readable when hosted stand-alone; the resulting box
is always centered. --box-width accepts the same
arguments the css max-width attribute accepts, e.g. 25cm
or 800px.
-a TOC, --toc TOC Enables the use of `[[_TOC_]]`, `{:toc}` and `[toc]`
at the beginning of an otherwise empty line to create a
table of content for the document. These syntax are
supported by different markdown flavors, the most
prominent probably being GitLab-flavored markdown
(supports `[[_TOC_]]`), and since GitLab displays its
READMEs quite similar to how GitHub does it, this option
was added to improve support for GitLab- flavored
markdown.
ดังที่ได้กล่าวไว้ข้างต้นรูปภาพใด ๆ ที่อ้างถึงในไฟล์ Markdown จะถูกเก็บไว้ในเครื่องและอ้างอิงโดยใช้ไฮเปอร์ลิงก์รูทสัมพันธ์ใน HTML ที่สร้างขึ้น วิธีที่ตัวแปลงคาดเดาตำแหน่งของภาพจะแสดงในตารางต่อไปนี้ด้วยประเภทของ imageLink ที่ระบุไว้ที่ด้านบนและประเภทของการทำเครื่องหมายอินพุตที่ระบุไว้ทางด้านซ้าย:
https:// หรือ http:// | กลบีเอ ฟีเจอร์ | Rel ฟีเจอร์ | เริ่มต้นด้วย / (เช่น /imagedir/image.png ) | ไม่เริ่มต้นด้วย / (เช่น imagedir/image.png ) | |
|---|---|---|---|---|---|
-t file | จากที่อยู่ | กลบีเอ ฟีเจอร์ | Rel FilePath (จากที่ .md -File อยู่) | - | - |
-t string | จากที่อยู่ | abs.filepath แต่ต้องการการยืนยันด้วยเหตุผลด้านความปลอดภัย | Rel FilePath (ไปยังที่ที่เครื่องมือถูกเรียก) แต่ต้องการการยืนยันด้วยเหตุผลด้านความปลอดภัย | - | - |
username/repo/dir/file.md -t repo | จากที่อยู่ | - | - | username/repo/imagedir/image.png | username/repo/dir/imagedir/image.png |
https://foo.com/bar/baz.md -t web | จากที่อยู่ | - | - | https://foo.com/image.png | https://foo.com/bar/image.png |
เช่นเดียวกับโครงการทั้งหมดของฉันข้อเสนอแนะ (แม้ว่ามันจะเป็นเพียงสิ่งเล็ก ๆ น้อย ๆ เช่นบอกฉันกรณีการใช้งานของคุณสำหรับโครงการของฉันหรือบอกฉันว่าคุณไม่ชอบโครงสร้างของ readme หรือบอกฉันว่าคุณชอบคุณลักษณะเฉพาะหนึ่งอย่าง) เป็นที่นิยมมากและช่วยให้ฉันทำให้โครงการนี้ดีขึ้นแม้ว่ามันจะเล็กมาก! คุณสามารถลดปัญหาด้วยความคิดเห็นสั้น ๆ และไม่เป็นทางการหรือแม้แต่ส่งอีเมลถึงฉันหากคุณไม่ต้องการยกปัญหาด้วยเหตุผลบางอย่าง ฉันไม่ได้วางแผนที่จะเพิ่มคุณสมบัติในอนาคตในขณะนี้ แต่ฉันมักจะเปิดรับการแก้ไขและปรับแต่งคุณสมบัติที่มีอยู่เอกสารและ cetera และเห็นได้ชัดว่าฉันชอบที่จะได้ยินคำแนะนำคุณสมบัติของคุณแม้ว่าฉันจะไม่ได้วางแผนที่จะเพิ่มพวกเขาในอนาคตอันใกล้
โดยทั่วไปฉันตอบสนองอย่างมากเมื่อพูดถึงปัญหาของ GitHub และฉันก็จริงจังกับพวกเขาอย่างจริงจังและพยายามแก้ปัญหาโดยเร็ว หากคุณพบข้อบกพร่องพฤติกรรมแปลก ๆ ข้อผิดพลาดในการติดตั้งและสิ่งที่คล้ายกันในขณะที่ใช้เครื่องมือของฉันอย่าลังเลที่จะบอกฉันในปัญหาดังนั้นฉันจึงสามารถแก้ไขปัญหาได้!
หากคุณพบว่าเครื่องมือนี้มีประโยชน์โปรดพิจารณานำแสดงโดย GitHub เพื่อแสดงความขอบคุณ! ฉันจะขอบคุณถ้าคุณบอกฉันเกี่ยวกับปัญหาที่คุณพบแม้ว่าคุณจะจัดการเพื่อแก้ไขในสำเนารหัสของคุณเองดังนั้นฉันจึงสามารถแก้ไขได้ใน repo นี้เช่นกัน
gh-md-to-html สำหรับการแปลง MD-to-PDF (ภายใต้ GIST เกี่ยวกับการแปลง MD-to-PDF): ลิงก์gh-md-to-html ในเอกสารของโครงการอื่น: ลิงก์ไอคอนทำโดย
.md-file.icon: freepik จาก flaticon.com
.md-file.icon: freepik จาก flaticon.com
Arrow-icon: Font Awesome โดย Dave Gandy ได้รับใบอนุญาตภายใต้ Creative Commons แหล่งที่มา-แชร์ 3.0 Unported
GitHub-icon: ไอคอน gitHub บน iconScout
ข้อจำกัดความรับผิดชอบ : โมดูลนี้ไม่ได้เขียนโดย GitHub และไม่ได้รับการรับรองด้วย GitHub ซึ่งได้รับการสนับสนุนโดย GitHub ขับเคลื่อนโดย GitHub หรือเกี่ยวข้องกับ GitHub มันใช้ API สาธารณะที่จัดทำโดย GitHub รวมถึง. css-file ที่ได้รับอนุญาตจาก GitHub ภายใต้ใบอนุญาต MIT
