ทำงานกับ README.md บน github.com [ปิด]

ฉันไม่คุ้นเคยกับภาษามาร์กอัปแบบเบาที่ github ใช้เมื่ออัปเดตไฟล์ README

แหล่งข้อมูลที่ฉันสามารถอ่านเกี่ยวกับวิธีการเขียนไวยากรณ์มาร์กอัปที่เหมาะสมสำหรับไฟล์ README / wiki ของไลบรารีโอเพนซอร์สของฉันอยู่ที่ไหน

และมีเครื่องมือใดบ้างที่ฉันสามารถ "ตรวจสอบเอกสารของฉันในเครื่องในเบราว์เซอร์" ก่อนที่จะส่ง README ที่อัปเดตไปยังที่เก็บ github ของฉัน

มาร์กอัปในคำถามที่เรียกว่าบังเอิญMarkdownสร้างโดยจอห์นกรูเบอร์เขียนบล็อก Daring Fireball แหล่งเดิมของ Markdown สามารถพบได้ที่Daring Fireball - Markdown

มีภาษา Markdown จำนวนมากเอกสารสำหรับ Github สามารถพบได้บนGithub รส Markdownหน้า

เคล็ดลับดีๆจากหน้านั้น:

กดMบนหน้า Github ใดก็ได้โดยใช้ตัวแก้ไข Markdown เพื่อเปิด Cheatsheet

คุณยังสามารถใช้หน้าGithub Markdown Live Previewเพื่อทดสอบเอกสาร Markdown ของคุณ

อัปเดต 2012-11-08 : กำลังดำเนินการเพื่อสร้างมาตรฐานของไวยากรณ์ Markdown ดูอนาคตของ Markdown - เจฟฟ์แอด Coding สยองขวัญและW3C กลุ่มชุมชน

Update 2014-09-09 : CommonMarkมาตรฐาน markdown และข้อมูลจำเพาะได้รับการเผยแพร่

( โพสต์คำตอบนี้ซ้ำพร้อมการแก้ไขบางส่วน)

เล่นเกมช้าไปหน่อย แต่ฉันเขียน CLI เล็ก ๆ ใน Python มันเรียกว่าGrip (Github Readme ดูตัวอย่างทันที) นอกเหนือจากคำตอบของ Patrick แล้วสิ่งนี้จะช่วยให้คุณสามารถ "ตรวจสอบเอกสารของฉันได้ในเบราว์เซอร์ของฉัน"

ติดตั้งด้วย:

$ pip install grip

และในการใช้งานเพียง:

$ grip

จากนั้นlocalhost:5000เข้าไปดูreadme.mdไฟล์ที่ตำแหน่งนั้น

คุณยังสามารถระบุไฟล์ของคุณเอง:

$ grip CHANGES.md

และเปลี่ยนพอร์ต:

$ grip 8080

หรือรวมสองรายการก่อนหน้านี้:

$ grip CHANGES.md 8080

คุณยังสามารถเรนเดอร์มาร์กดาวน์ GitHub-Flavored (เช่นวิธีแสดงความคิดเห็นและปัญหา) โดยสามารถเลือกใช้บริบท repo เพื่ออ้างอิงไฮเปอร์ลิงก์อัตโนมัติไปยังปัญหาอื่น ๆ ได้:

$ grip --gfm --context=username/repo issue.md

เพื่อความกะทัดรัดโปรดดูตัวเลือกที่เหลือและรายละเอียดโดยใช้ความช่วยเหลือ CLI:

$ grip -h

คุณสมบัติเด่น:

• แสดงผลหน้าเว็บให้เหมือนกับบน GitHub
• บล็อกรั้ว
• Python API
• นำทางระหว่างไฟล์ที่เชื่อมโยง
• ส่งออกเอกสารที่แสดงผลไปยังไฟล์

หวังว่านี่จะช่วยได้ ลองดูสิ

มีโปรแกรมแก้ไขออนไลน์ / สดที่ดีที่นี่:

http://jbt.github.io/markdown-editor/

นอกจากนี้ยังมีPreviewปุ่มที่ GitHub

README.mdเห็นในหน้าจอต่อไปนี้ที่ปุ่มนี้จะปรากฏขึ้นเมื่อฉันคลิกแก้ไขบน

IMHO โปรแกรมแก้ไขสดดีกว่าตัวแก้ไขปัจจุบันที่มีอยู่ใน GitHub

อัปเดต

ตอนนี้ฉันพบหลังจากค้นหาMarkdownและ Visual Studio ว่าหากคุณใช้ VS คุณสามารถติดตั้งWeb Essentialsและได้Markdownรับการสนับสนุนจากภายใน Visual Studio เจ๋งมาก!

มันมี:

• การเน้นไวยากรณ์ => การกำหนดสีแบบเต็มสำหรับไวยากรณ์ Markdown
• Intellisense สำหรับภาษาฝังตัว ( W00T ) => คุณลักษณะภาษาฝังตัวของ GitHub ได้รับการสนับสนุนอย่างสมบูรณ์โดยการสนับสนุนสำหรับไวยากรณ์ภาษา ``

• หน้าต่างแสดงตัวอย่าง => ดูหน้าต่างแสดงตัวอย่างแบบเคียงข้างกันของ HTML ที่แสดงผล
• คอมไพล์เป็น HTML => คลิกขวาที่ไฟล์ Markdown และเลือก Compile Markdown to HTML สิ่งนี้จะสร้างไฟล์. html ที่ซ้อนอยู่ใต้ไฟล์ Markdown และไฟล์จะยังคงซิงค์อยู่เมื่อไฟล์ Markdown เปลี่ยนแปลง
• สไตล์ชีตแบบกำหนดเอง => คุณสามารถเพิ่มสไตล์ชีตเฉพาะโซลูชันเพื่อควบคุมสไตล์ของหน้าต่างแสดงตัวอย่าง

รายละเอียดเกี่ยวกับเรื่องนี้ที่นี่

โปรดทราบว่าตั้งแต่เดือนกุมภาพันธ์ 2014 เป็นต้นมาคุณสามารถดูเวอร์ชันที่แสดงผลของความแตกต่างในไฟล์ markdown ได้ด้วย:

กระทำและการร้องขอดึงรวมถึงไฟล์ร้อยแก้วตอนนี้แหล่งที่มาคุณสมบัติและมุมมองการแสดงผล

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

อีกทางเลือกหนึ่ง - โปรแกรมแก้ไขข้อความใหม่ของ Github Atom จะแสดงผลมาร์กดาวน์ที่มีรส Github เมื่อคุณแก้ไข ดูhttps://atom.io/

ฉันไม่แน่ใจว่ามันจะฟรี (เช่นเดียวกับเบียร์) ในระยะยาวหรือไม่

ณ วันนี้คุณสามารถดูตัวอย่างในขณะที่คุณแก้ไขไฟล์

ฉันไม่พบว่าเครื่องมืออื่นดีพอ - ฉันต้องการ:

1. ความสามารถในการแก้ไขแบบออฟไลน์
2. ไม่ใช่แค่การมาร์กดาวน์ปกติ แต่เป็นมาร์กดาวน์ที่ปรุงแต่งของ Github

นี่คือสิ่งที่ฉันตัดสินในที่สุด: https://github.com/ypocat/gfms

> gfms

Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms

Options:
  -p, --port              Port number to listen at.        [required]
  -h, --host              Host address to bind to.         [default: "localhost"]
  --proxy                 if behind a proxy, proxy url.
  -a, --api               Render using Github API.
  -n, --no-api-on-reload  Disable usage of Github API when the doc is manually reloaded.

ดังนั้นฉันจึงใช้นามแฝง:

alias gm='gfms -a -p 8070'

การใช้-pตัวเลือกนี้เข้ากับ Github API และใช้ Github CSS ปัจจุบันที่แท้จริงจึงไม่น่าแปลกใจใด ๆ