Github.com'da README.md ile çalışma [kapalı]

README dosyalarını güncellerken github tarafından kullanılan hafif biçimlendirme diline pek aşina değilim.

Açık kaynak kitaplığımın README / wiki dosyaları için uygun işaretleme sözdizimini nasıl yazacağımı okuyabileceğim kaynaklar nerede?

Ve güncellenmiş README'yi github havuzuma göndermeden önce "dokümanlarımı tarayıcımda yerel olarak inceleyebileceğim" bir araç var mı?

Daring Fireball blogunun yazarı John Gruber tarafından yaratılan söz konusu işaretleme tesadüfen Markdown olarak adlandırılıyor . Markdown'un orijinal kaynağı Daring Fireball - Markdown'da bulunabilir .

Birçok Markdown lehçesi vardır, Github'ların belgeleri Github Flavored Markdown sayfasında bulunabilir.

o sayfadan güzel bir ipucu:

Hile sayfasını ortaya çıkarmak için bir Markdown editörü olan herhangi bir Github sayfasında M tuşuna basın .

Markdown belgelerinizi test etmek için Github Markdown Canlı Önizleme sayfasını da kullanabilirsiniz .

Güncelleme 2012-11-08 : Markdown sözdizimini standartlaştırma çabaları devam ediyor. Bkz Jeff Atwood, Kodlama Korku - Markdown Geleceği ve W3C Markdown Topluluk Grubu .

2014-09-09 Güncellemesi : CommonMark bir fiyat düşüş standardı ve spesifikasyonu yayınlandı.

( Bu yanıtı bazı düzenlemelerle yeniden yayınlayın .)

Oyuna biraz geç kaldım ama Python'da küçük bir CLI yazdım. Adı Grip (Github Readme Instant Preview) . Patrick'in cevabına ek olarak, bu "dokümanlarımı tarayıcımda yerel olarak gözden geçirmenize" olanak tanıyacak.

Şununla kurun:

$ pip install grip

Ve kullanmak için basitçe:

$ grip

Ardından localhost:5000, readme.mddosyayı bu konumda görüntülemek için adresini ziyaret edin .

Ayrıca kendi dosyanızı da belirtebilirsiniz:

$ grip CHANGES.md

Ve bağlantı noktasını değiştirin:

$ grip 8080

Veya önceki ikisini birleştirin:

$ grip CHANGES.md 8080

Hatta GitHub-Aromalı Markdown (yani yorumların ve sorunların nasıl işlendiği), isteğe bağlı olarak diğer sorunlara otomatik köprü referansları için repo bağlamı ile render edebilirsiniz:

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

Kısalık için, CLI yardımını kullanarak diğer seçeneklere ve ayrıntılarına bakın:

$ grip -h

Önemli özellikler:

• Sayfaları tam olarak GitHub'daki gibi görünecek şekilde oluşturur
• Çitle çevrili bloklar
• Python API
• Bağlı dosyalar arasında gezinin
• İşlenmiş bir belgeyi bir dosyaya dışa aktarma

Bu yardımcı olur umarım. Kontrol edin .

Burada güzel bir çevrimiçi / canlı düzenleyici var:

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

PreviewGitHub'da bir düğme de var.

Aşağıdaki ekran görüntüsünde, Düzenle'yi tıkladığımda bu düğmenin göründüğüne bakın README.md.

IMHO canlı düzenleyici , GitHub'da mevcut olandan daha iyidir.

GÜNCELLEME

Az önce Markdownve Visual Studio'yu aradıktan sonra , VS kullanıyorsanız, Web Essentials'ı yükleyebileceğinizi ve Markdowndoğrudan Visual Studio içinden destek alabileceğinizi öğrendim . Çok havalı!

Şunlara sahiptir:

• Sözdizimi vurgulama => Markdown sözdizimi için tam renklendirme
• Gömülü diller için Intellisense ( W00T ) => GitHub'ın gömülü dil özelliği, `` dil sözdizimi '' desteği ile tam olarak desteklenir.

• Önizleme penceresi => Oluşturulan HTML'nin yan yana önizleme penceresini görün
• HTML'ye derleyin => Herhangi bir Markdown dosyasına sağ tıklayın ve Markdown'u HTML'ye Derle'yi seçin. Bu, Markdown dosyasının altına yerleştirilmiş bir .html dosyası oluşturacak ve Markdown dosyası değiştikçe senkronize kalacaktır.
• Özel Stil Sayfası => Önizleme penceresinin stillerini kontrol etmek için çözüme özel bir Stil Sayfası ekleyebilirsiniz.

Bununla ilgili ayrıntılar burada .

Şubat 2014'ten bu yana, " Oluşturulmuş Düzyazı Farklılıkları " ile, bir farkın oluşturulmuş sürümünü bir markdown dosyasında da görebileceğinizi unutmayın:

Düzyazı dosyaları dahil olmak üzere kaydetme ve çekme istekleri artık kaynak ve işlenmiş görünümler içeriyor .

Metin olmayan değişiklikler, düşük anahtar noktalı altı çizili olarak görünür. Nelerin değiştiğini görmek için metnin üzerine gelin:

Başka bir seçenek - Github'ın yeni metin editörü Atom, siz düzenlerken github aromalı markdown işleyecektir. Bkz https://atom.io/

Uzun vadede (birada olduğu gibi) bedava olup olmayacağından emin değilim.

Bugün itibariyle, dosyayı düzenlerken önizleme yapabilirsiniz.

Diğer araçların yeterince iyi olduğunu bulamadım - şunu istedim:

1. Çevrimdışı düzenleme yeteneği
2. Sadece normal fiyat indirimi değil, gerçek Github aromalı fiyat indirimi

Nihayetinde karar kıldım: 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.

Ben de takma ad verdim:

alias gm='gfms -a -p 8070'

-pSeçeneği kullanmak Github API'sine ulaşır ve gerçek, mevcut Github CSS'yi kullanır, böylece herhangi bir sürpriz olmaz.