Bekerja dengan README.md di github.com [ditutup]

Saya tidak terlalu paham dengan bahasa markup ringan yang digunakan oleh github saat memperbarui file README.

Di manakah sumber daya yang dapat saya baca tentang cara menulis sintaks markup yang sesuai untuk file README / wiki perpustakaan sumber terbuka saya?

Dan adakah alat yang dapat saya gunakan untuk "meninjau dokumen saya secara lokal di browser saya" sebelum memasukkan README yang diperbarui ke repositori github saya?

Markup yang dimaksud secara kebetulan disebut Markdown , dibuat oleh John Gruber, penulis blog Daring Fireball . Sumber asli penurunan harga dapat ditemukan di Daring Fireball - penurunan harga .

Ada banyak dialek penurunan harga, dokumentasi untuk Github dapat ditemukan di halaman penurunan harga rasa Github .

tip bagus dari halaman itu:

tekan M di halaman Github mana pun dengan editor penurunan harga untuk membuka cheatsheet.

Anda juga dapat menggunakan halaman Pratinjau Langsung Penurunan Harga Github untuk menguji dokumen Penurunan Harga Anda.

Pembaruan 2012-11-08 : Upaya sedang dilakukan untuk menstandarisasi sintaks penurunan harga. Lihat Masa Depan Penurunan Harga - Jeff Atwood, Coding Horror dan Kelompok Komunitas Penurunan Harga W3C .

Pembaruan 2014-09-09 : CommonMark standar penurunan harga dan spesifikasi telah dirilis.

( Posting ulang jawaban ini dengan beberapa pengeditan.)

Sedikit terlambat ke permainan, tapi saya menulis CLI kecil dengan Python. Ini disebut Grip (Github Readme Instant Preview) . Menambah jawaban Patrick, ini akan memungkinkan Anda "meninjau dokumen saya secara lokal di browser saya."

Instal dengan:

$ pip install grip

Dan untuk menggunakannya, cukup:

$ grip

Kemudian kunjungi localhost:5000untuk melihat readme.mdfile di lokasi itu.

Anda juga dapat menentukan file Anda sendiri:

$ grip CHANGES.md

Dan ubah port:

$ grip 8080

Atau gabungkan dua sebelumnya:

$ grip CHANGES.md 8080

Anda bahkan dapat merender GitHub-Flavored Markdown (yaitu bagaimana komentar dan masalah ditampilkan), secara opsional dengan konteks repo ke referensi hyperlink otomatis ke masalah lain:

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

Untuk singkatnya, lihat opsi lainnya dan detailnya menggunakan bantuan CLI:

$ grip -h

Fitur penting:

• Merender halaman agar tampak persis seperti di GitHub
• Blok berpagar
• Python API
• Menavigasi di antara file yang ditautkan
• Ekspor dokumen yang dirender ke file

Semoga ini membantu. Coba lihat .

Ada editor online / live yang bagus di sini:

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

Ada juga Previewtombol di GitHub.

Lihat di tangkapan layar berikut bahwa tombol ini muncul ketika saya mengklik Edit README.md.

IMHO editor langsung lebih baik daripada yang saat ini tersedia di GitHub.

MEMPERBARUI

Baru saja saya menemukan setelah mencari Markdowndan Visual Studio bahwa jika Anda menggunakan VS, Anda dapat menginstal Web Essentials dan memiliki Markdowndukungan langsung dari dalam Visual Studio. Itu keren!

Memiliki:

• Penyorotan sintaks => Pewarnaan penuh untuk sintaks Markdown
• Intellisense untuk bahasa yang disematkan ( W00T ) => Fitur bahasa yang disematkan GitHub didukung sepenuhnya oleh dukungan untuk `` sintaks bahasa.

• Jendela pratinjau => Lihat jendela pratinjau berdampingan dari HTML yang dirender
• Compile to HTML => Klik kanan file Markdown apapun dan pilih Compile Markdown to HTML. Ini akan menghasilkan file .html yang berada di bawah file Penurunan Harga dan akan tetap tersinkronisasi saat file Penurunan Harga berubah.
• Custom Stylesheet => Anda dapat menambahkan solusi Stylesheet tertentu untuk mengontrol gaya jendela pratinjau.

Detail tentangnya di sini .

Perhatikan bahwa sejak Februari 2014, dengan " Rendered Prose Diffs ", Anda juga dapat melihat versi render dari diff pada file penurunan harga:

Commit dan pull request termasuk file prosa sekarang menampilkan sumber dan tampilan yang dirender .

Perubahan non-teks muncul dengan garis bawah bertitik kunci rendah. Arahkan kursor ke teks untuk melihat apa yang berubah:

Opsi lain - editor teks baru Github, Atom, akan membuat penurunan harga rasa github saat Anda mengeditnya. Lihat https://atom.io/

Saya tidak yakin apakah itu akan gratis (seperti bir) dalam jangka panjang.

Mulai hari ini, Anda dapat mempratinjau, saat Anda mengedit file.

Saya tidak menemukan bahwa alat lain cukup baik - saya ingin:

1. Kemampuan untuk mengedit secara offline
2. Bukan hanya penurunan harga biasa, tetapi penurunan harga rasa Github yang sebenarnya

Inilah yang akhirnya saya putuskan: 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.

Jadi saya telah alias:

alias gm='gfms -a -p 8070'

Menggunakan -popsi ini mengenai API Github dan menggunakan CSS Github saat ini yang sebenarnya sehingga tidak ada kejutan.