Apa itu file README "diformat-markdown" di Github?

27

Tidak jelas bagi saya apa formatnya, apakah ada persyaratan sistematis / command-line untuk membuatnya, dll.

Pada dasarnya, hanya perlu mengetahui spesifikasi, dan jika ada langkah-langkah teknis untuk menghasilkan file README.

github kesalahan besar
sumber
4
Tidak, hanya file teks yang Anda edit dengan tangan. Sedangkan untuk sintaks, en.wikipedia.org/wiki/Markdown
Andrea
3
ini adalah format edit wiki yang sama yang digunakan pihak ini.
k3b
+1 @Andrea: Terima kasih, meskipun saya bisa memikirkan lebih dari beberapa format penurunan harga, format dan versi apa yang diharapkan di Github? Juga, komentar Anda dibaca sebagai lebih banyak jawaban, silakan posting sebagai jawaban lengkap. Sekali lagi terima kasih!
kesalahan
+1 @ K3b: Percayalah Anda sedang melakukan sesuatu, apakah Anda berbicara tentang penggunaan Gollum oleh Github , yang misalnya memungkinkan tautan relatif? Jika demikian, silakan posting ini sebagai jawabannya, karena saya percaya itu jawaban yang benar. Terima kasih!
kesalahan

Jawaban:

37

Penurunan harga adalah sintaksis sederhana untuk memberikan info semantik dan mewakili format umum dalam teks biasa. Daring Fireball memiliki panduan sintaks yang luar biasa untuk penurunan standar . GitHub kemudian menggunakan varian ini yang mereka sebut GitHub Flavoured Markdown .

Untuk menyiapkan readme Anda cukup buat file teks biasa dan beri nama README (atau README.md / README.markdown) dan komit ke root repo Anda. GitHub kemudian akan mengambil ini sebagai readme proyek.

Kim Burgess
sumber
2
Saya juga membuat video yang menjelaskan cara menggunakan Markdown. Anda dapat menemukannya di sini: mikemclin.net/markdown-syntax-language
Mike McLin
9

Wikipedia - Penurunan harga referensi halaman "GitHub Flavoured Markdown - Introduction" ( archv. )

Kutipan dari halaman:

GitHub menggunakan apa yang kami sebut "GitHub Flavoured Markdown" (GFM) untuk pesan, masalah, dan komentar. Ini berbeda dari Markdown standar (SM) dalam beberapa cara yang signifikan dan menambahkan beberapa fungsi tambahan.

Halaman ini juga memberikan deskripsi perbedaan untuk penurunan harga standar.

Ada juga informasi lebih lanjut tentang penurunan harga sebenarnya yang dilakukan oleh GitHub:

Jika Anda tertarik dengan cara kami merender file Penurunan harga, Anda mungkin ingin memeriksa Redcarpet , antarmuka Ruby kami ke perpustakaan Sundown .

(Rupanya, Sundown adalah parser Markdown sebenarnya yang digunakan di balik tirai.)

Untuk menambahkan satu lapisan abstraksi lagi, Sundown adalah garpu dari parser penurunan harga lainnya :-)
Kutipan dari halaman GitHub Sundown :

Sundown adalah parser Markdown berdasarkan kode asli perpustakaan Upskirt oleh Natacha Porté.

Christian Specht
sumber
1

Ini sangat aneh, tetapi sepertinya GitHub tidak menggunakan GitHub-Flavoured Markdown (GFM) saat merender file README.

GitHub menggunakan "GitHub Flavoured Markdown," atau GFM, di seluruh situs - dalam masalah, komentar, dan permintaan tarik.

Alih-alih tampaknya menggunakan versi yang disebut redcarpet sebagai bagian dari proyek markup GitHub . Mereka juga mendukung beberapa format markup lainnya, termasuk MediaWiki. Cukup gunakan ekstensi file yang tepat, dan GitHub akan membuat markup.

Jika Anda ingin melihat perbedaan antara dua rasa Markdown yang berbeda, baca deskripsi GFM dan fitur-fitur tambahannya .

Don Kirkby
sumber
1
redcarpet dan Github Flavoured Markdown adalah dua konsep yang terpisah namun saling melengkapi, tidak bersaing dengan implementasi dari hal yang sama. redcarpet pada dasarnya adalah sebuah compiler yang mengambil sesuatu yang tertulis dalam Github Flavored penurunan harga bahasa dan output HTML atau XHTML.
8bittree