Apakah ada utilitas baris perintah untuk rendering GitHub Markdown rasa?


414

Saya bertanya-tanya apakah ada utilitas baris perintah untuk mengambil file Markdown beraroma GitHub dan merendernya ke HTML.

Saya menggunakan wiki GitHub untuk membuat konten situs web. Saya telah mengkloning repositori di server saya dan kemudian ingin memprosesnya menjadi HTML biasa. Penting bagi saya bahwa apa yang muncul di GitHub adalah bagaimana seharusnya mencari situs web saya. Saya juga sangat suka menggunakan blok berpagar ~~~, jadi saya lebih suka tidak menggunakan sintaks Markdown standar saja.

Saya telah melihat sedikit ke preview JavaScript hidup berpikir saya bisa menghubungkannya ke Node.js, tetapi mereka mengatakan itu sudah usang. Saya telah melihat repositori redcarpet, tetapi sepertinya tidak memiliki antarmuka baris perintah.

Saya menggulung solusi saya sendiri, karena tidak ada solusi di sini yang jelas lebih baik daripada yang lain, saya akan meninggalkan pertanyaan tanpa jawaban yang dipilih.


2
RE: PEMBARUAN: Jika saya menambahkan --outargumen untuk menangani membuat file HTML bukan browser, apakah itu dapat diterima?
Joe

@Joe tolong tambahkan opsi itu!
bguiz

@McLeopold @bguiz baru saja menggunakan --exportopsi, yang menjadikan GFM dan gayanya menjadi satu file. Apakah ini menjawab pertanyaan?
Joe

3
@ McLeopold, Joe membuat ini keluar dari taman dengan menciptakan solusi sederhana yang dapat digunakan kembali, mungkin ingin memberikan jawabannya.
James McMahon

1
Github sendiri menggunakan Sundown . Lihat stackoverflow.com/a/7694931/632951
Pacerier

Jawaban:


447

Saya menulis CLI kecil dengan Python dan menambahkan dukungan GFM. Ini disebut Grip (Github Readme Instant Preview) .

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 ganti port:

$ grip 8080

Dan tentu saja, secara khusus membuat GitHub-Flavoured Markdown, opsional dengan konteks repositori:

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

Fitur-fitur penting:

  • Render halaman agar muncul persis seperti di GitHub
  • Blok berpagar
  • API Python
  • Menavigasi antara file yang tertaut (terima kasih, vladwing !) Ditambahkan dalam 2.0
  • Ekspor ke satu file (terima kasih, iliggio !) Ditambahkan dalam 2.0
  • Baru: Baca dari stdindan ekspor untuk stdout ditambahkan dalam 3.0

Semoga ini bisa membantu seseorang di sini. Lihat itu .


1
Bekerja sangat baik dan Anda tidak bisa mengalahkan kemudahan instalasi untuk Pythonistas!
RichVel

29
Ini harus menjadi hit pertama untuk "pratinjau penurunan harga github." Yang lainnya rumit, tidak berfungsi, atau tidak melakukan semua fitur GitHub. gripbekerja tepat di luar kotak.
Bluu

1
@Houdini Masalah itu sudah usang. Flask mendukung 3.3, lihat flask.pocoo.org/docs/python3 . Inilah utas Github yang lebih baru tentang topik github.com/mitsuhiko/flask/issues/587 . Jika ada ketergantungan lain yang perlu diperbarui, jangan ragu untuk membuka masalah atau permintaan tarik.
Joe

3
Perlu dicatat bahwa paket ini membutuhkan koneksi internet aktif dan kredensial autentikasi github Anda (disediakan pada baris perintah) jika Anda melakukan lebih dari 60 refresh per jam.
leo

13
Seperti yang disebutkan sebelumnya, saya tidak berpikir ini adalah solusi yang sangat bagus karena semua yang dilakukannya itu pergi ke Github dan membuat Github untuk membuat penurunan harga Anda. Dibutuhkan koneksi internet yang berfungsi dengan akses ke Github, dan jika Github mati maka alat ini berhenti berfungsi. Saya lebih suka memiliki solusi yang sepenuhnya offline.
Jez

114

Saya belum menemukan metode cepat dan mudah untuk Markdown rasa GitHub, tetapi saya telah menemukan versi yang sedikit lebih umum - Pandoc . Itu mengkonversi dari / ke sejumlah format, termasuk penurunan harga, istirahat, HTML dan lainnya.

Saya juga telah mengembangkan Makefileuntuk mengonversi semua file .md ke .html (sebagian besar pada contoh di Writing, Markdown, dan Pandoc ):

# 'Makefile'
MARKDOWN = pandoc --from gfm --to html --standalone
all: $(patsubst %.md,%.html,$(wildcard *.md)) Makefile

clean:
    rm -f $(patsubst %.md,%.html,$(wildcard *.md))
    rm -f *.bak *~

%.html: %.md
    $(MARKDOWN) $< --output $@

4
Saya telah menggunakan "watch pandoc ..." untuk secara terus-menerus mengonversi file penurunan harga menjadi html, dan ekstensi "live reload" chrome untuk mendapatkan waktu nyata "tetap di tempat saya menggulir juga" fungsionalitas dengan ini, dan itu berfungsi dengan baik . chrome.google.com/webstore/detail/livereload/…
Brad Parks

1
Pandoc membaca GFM baik-baik saja tetapi tidak menghasilkan HTML yang sama dengan GitHub - misalnya, jika Anda memiliki <pre/>tag multi-baris di sumber GFM Anda, Pandoc akan memasukkan <br/>tag untuk jeda baris di dalamnya, sementara renderer GitHub, meskipun itu strip spasi putih terkemuka, tampaknya jika tidak meninggalkan konten sendirian.
David Moles

1
Bagaimana cara mendapatkan gaya yang bagus pada HTML yang dihasilkan? Output saya masih diterjemahkan dengan Times New Roman, misalnya.
Pengembang Holistik

Instruksi instalasi Pandoc ada di sini . Di macOS:brew install pandoc
Master of Ducks

1
baik format input gfmmaupun markdown_githubbenar tidak membuat hal-hal seperti blok kode.
user5359531

29

Mungkin ini bisa membantu:

gem install github-markdown

Tidak ada dokumentasi, tetapi saya mendapatkannya dari dokumentasi gollum . Melihat rubydoc.info , sepertinya Anda dapat menggunakan:

require 'github/markdown'  
puts GitHub::Markdown.render_gfm('your markdown string')

dalam kode Ruby Anda. Anda bisa membungkusnya dengan mudah dalam skrip untuk mengubahnya menjadi utilitas baris perintah:

#!/usr/bin/env ruby

# render.rb
require 'github/markdown'

puts GitHub::Markdown.render_gfm File.read(ARGV[0])

Jalankan dengan ./render.rb path/to/my/markdown/file.md. Perhatikan bahwa ini tidak aman untuk digunakan dalam produksi tanpa sanitasi.


1
Terima kasih Jim, karena contoh-contoh yang hampir tidak ada, saya terjebak pada langkah yang diperlukan (mengganti dash dengan slash membuatnya) ..;)
plesatejvlk

Ini bagus jika Anda sudah menggunakan NPM. Saya harus menggunakannya, karena DOxygen menyebabkan saya terus-menerus mengalami masalah dengan penurunan harga khusus + github + mengekspor ke HTML.
kayleeFrye_onDeck

apakah ini berjalan secara lokal atau mengirim data ke API GitHub?
user5359531

28
pip3 install --user markdown
python3 -m markdown readme.md > readme.html

Itu tidak menangani ekstensi GitHub, tetapi lebih baik daripada tidak sama sekali. Saya percaya Anda dapat memperluas modul untuk menangani penambahan GitHub.


1
/ usr / bin / python: markdown adalah sebuah paket dan tidak dapat langsung dieksekusi
Kazimieras Aliulis

2
Output HTML sederhana tanpa tag mewah.
Halil Kaskavalci

23

Mungkin bukan yang Anda inginkan, tetapi karena Anda menyebutkan Node.js: Saya tidak dapat menemukan alat yang bagus untuk melihat pratinjau dokumentasi GitHub Flavoured Markdown pada drive lokal saya sebelum memasukkannya ke GitHub, jadi hari ini saya membuat satu, berdasarkan Node.js: https : //github.com/ypocat/gfms

Jadi mungkin Anda dapat menggunakan kembali showdown.js dari itu untuk Wiki Anda, jika pertanyaan Anda masih aktual. Jika tidak, mungkin orang lain yang menghadapi masalah yang sama seperti saya akan menemukan (sama seperti saya) pertanyaan ini dan jawaban ini.


Bagus, bung. Menghemat saya dari keharusan menggunakan Ruby atau Python ketika saya sedang menulis aplikasi simpul, yang bagus.
jedd.ahyoung

19

Untuk membaca file README.md di terminal yang saya gunakan:

pandoc README.md | lynx -stdin

Pandoc menampilkannya dalam format HTML, yang dirender oleh Lynx di terminal Anda.

Ini berfungsi dengan baik: Ini mengisi terminal saya, jalan pintas diperlihatkan di bawah, saya dapat menggulir, dan tautannya bekerja! Hanya ada satu ukuran font, tetapi warna + indentation + alignment membuat untuk itu.

Instalasi:

sudo apt-get install pandoc lynx

1
Pertanyaannya secara khusus tentang penggunaan baris perintah. Sebelum menulis skrip ruby ​​Anda sendiri (atau server node egad), coba ini.
Cora Middleton

Tepatnya ini berfungsi di dalam terminal Anda. Atau jika browser favorit Anda (desktop?) Dapat mengakses folder yang digunakan pandoc readme.md -o readme.md.htmldan membuka file yang dihasilkan.
Barry Staes

@ baerry-staes Ya, maaf, saya harap jelas bahwa jawaban Anda adalah yang paling saya sukai.
Cora Middleton

@JustinMiddleton ya saya mengerti, terima kasih. Komentar saya hanya untuk menambahkan beberapa info tambahan untuk pengguna desktop .. saya pikir seseorang suatu hari nanti membaca ini mungkin berguna.
Barry Staes

1
Saya sudah mencoba sekitar 5-6 pembaca konsol md lainnya dan sejauh ini telah menjadi solusi terbaik. Saya baru saja menambahkan fungsi paling dasar ke konfigurasi saya untuk membuatnya sedikit lebih cepat digunakan. function md { pandoc $@ | lynx -stdin }
Russ Brown

17

GitHub memiliki API Penurunan harga yang dapat Anda gunakan.


5
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | curl --data @- https://api.github.com/markdown > README.html
Vebjorn Ljosa

@ VebjornLjosa * itu * atau grip... Anda pilih. : P
yyny

13

Gunakan yang ditandai . Ini mendukung GitHub Flavoured Markdown, dapat digunakan sebagai modul Node.js dan dari baris perintah.

Contohnya adalah:

$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>

1
Saya perhatikan bahwa ini tidak mendukung fitur seperti penyorotan sintaks untuk blok kode dan fitur yang lebih baru seperti daftar periksa. Tapi hei itu mendapat sebagian besar jalan!
bguiz

Sangat bagus, satu-satunya hal yang saya lewatkan adalah beberapa batas untuk tabel. Yah, setidaknya saya bisa membuat mereka sama sekali, ini persis seperti yang saya butuhkan. Pipa di GFM, pipa keluar HTML :)
Xandaros

Saya bingung tentang contoh ini, apa itu ^D?
Matius

10

Ini sebagian besar merupakan kelanjutan dari jawaban @ barry-staes untuk menggunakan Pandoc . Homebrew memilikinya juga, jika Anda menggunakan Mac:

brew install pandoc

Pandoc mendukung GFM sebagai format input melalui markdown_githubnama.

Output ke file

cat foo.md | pandoc -f markdown_github > foo.html

Buka di Lynx

cat foo.md | pandoc -f markdown_github | lynx -stdin # To open in Lynx

Buka di browser default pada OS X

cat foo.md | pandoc -f markdown_github > foo.html && open foo.html # To open in the default browser on OS X`

Integrasi TextMate

Anda selalu dapat menyalurkan seleksi saat ini atau dokumen saat ini ke salah satu di atas, karena sebagian besar editor memungkinkan Anda untuk melakukannya. Anda juga dapat dengan mudah mengkonfigurasi lingkungan sehingga pandocmenggantikan prosesor Markdown default yang digunakan oleh Markdown bundel .

Pertama, buat skrip shell dengan konten berikut (saya akan menyebutnya ghmarkdown):

#!/bin/bash
# Note included, optional --email-obfuscation arg
pandoc -f markdown_github --email-obfuscation=references

Anda kemudian dapat mengatur TM_MARKDOWNvariabel (dalam Preferensi → Variabel) untuk /path/to/ghmarkdown, dan itu akan menggantikan prosesor penurunan harga default.


10

Saya membuat alat yang mirip dengan fungsi Pratinjau Atom, tetapi sebagai aplikasi mandiri. Tidak yakin apakah ini yang Anda cari, tetapi mungkin bermanfaat. - https://github.com/yoshuawuyts/vmd

vmd


Kalian masih mendukung ini? Saya mencoba menginstal dengan NPM hari ini, tetapi tidak ada dadu. > mengunduh electron-v0.36.9-win32-x64.zip> Kesalahan: sertifikat yang ditandatangani sendiri
kayleeFrye_onDeck

1
Ya, benar! Versi npm / node tempat Anda menjalankan ini? - Jangan ragu untuk membuka masalah tentang GH dan kami akan melihat ini. Terima kasih!
Yoshua Wuyts

8

pandocdengan browserbekerja dengan baik untukku.

Pemakaian: cat README.md | pandoc -f markdown_github | browser

Instalasi (Anggap Anda menggunakan Mac OSX):

  • $ brew install pandoc

  • $ brew install browser

Atau di Debian / Ubuntu: apt-get install pandoc browser


1
apt-get isntall pandocakan lakukan, tidak perlu menggunakan tidak aman, barang-barang lokal seperti minuman.
Dominik George

1
@DominikGeorge ada kesalahan ketik, itu adalah menginstal , bukan isntall
Federico Tomassetti

11
@DominikGeorge tidak ada apt-get di macOS.
richrad

6

Lihat juga https://softwareengineering.stackexchange.com/a/128721/24257 .


Jika Anda tertarik dengan cara kami [Github] me-render file Markdown, Anda mungkin ingin memeriksa Redcarpet , antarmuka Ruby kami ke perpustakaan Sundown.

Script Ruby, yang menggunakan Redcarpet , akan menjadi "command line utility", jika Anda memiliki Ruby lokal


Belum punya ide - Saya tidak menulis Ruby dan saya tidak membaca sumber
Lazy Badger

@ LazyBadger, Sundown adalah parser yang sebenarnya (ditulis dalam C). Redcarpet tidak diperlukan.
Pacerier

6

Membangun pada komentar ini saya menulis satu-liner untuk menekan Github Markdown API menggunakan curldan jq.

Rekatkan fungsi bash ini ke baris perintah atau ke ~/.bash_profile:

mdsee(){ 
    HTMLFILE="$(mktemp -u).html"
    cat "$1" | \
      jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' | \
      curl -s --data @- https://api.github.com/markdown > "$HTMLFILE"
    echo $HTMLFILE
    open "$HTMLFILE"
}

Dan kemudian untuk melihat HTML di-browser yang dijalankan berjalan:

mdsee readme.md

Ganti open "$HTMLFILE"dengan lynx "$HTMLFILE"jika Anda membutuhkan solusi terminal murni.


4

GitHub telah (sejak) mengembangkan editor teks modular yang bagus yang disebut Atom (berdasarkan Chromium dan menggunakan modul Node.js untuk paket).

Paket pra-instal bawaan Markdown Preview memungkinkan Anda menampilkan pratinjau di tab terpisah menggunakan Ctrl+ Shift+ M.

Saya belum menguji sintaks lengkapnya, tetapi karena itu berasal dari GitHub, saya akan sangat terkejut jika sintaks pratinjau berbeda dari mereka (blok berpagar menggunakan ~~~ pekerjaan).

Sekarang, meskipun secara teknis tidak berbasis command-line, ia menggunakan Node.js dan output ke renderer berbasis DOM , yang dapat membantu siapa pun yang mencoba merender GitHub berbasis sintaksis HTML pada server web berbasis Node.js, atau hanya mengeditnya / offline README.md-nya.


1
Di Atom Anda dapat menginstal paket yang disebut gfm-pdf ( atom.io/packages/gfm-pdf ), yang mengekspor dokumen penurunan harga Anda ke dokumen HTML dan / atau PDF. Diperlukan perpustakaan wkhtmltopdf .
spren9er


3

Ada alat yang sangat bagus dan sederhana untuk menelusuri dokumen penurunan harga GFM:

GFMS - Github Flavoured Markdown Server

Ini sederhana dan ringan (tidak perlu konfigurasi) server HTTP yang dapat Anda mulai di direktori mana pun yang berisi file penurunan harga untuk menjelajahinya.

Fitur:

  • Dukungan GFM Markdown penuh
  • Menyoroti sintaksis kode sumber
  • Menelusuri file dan direktori
  • Output yang terlihat bagus (dan stylesheet CSS yang dapat dikonfigurasi)
  • Ekspor ke PDF

3

Saya berhasil menggunakan skrip Ruby satu baris untuk tujuan itu (walaupun harus masuk dalam file terpisah). Pertama, jalankan perintah ini sekali pada setiap mesin klien Anda akan mendorong dokumen dari:

gem install github-markup
gem install commonmarker

Selanjutnya, instal skrip ini di gambar klien Anda, dan sebut saja render-readme-for-javadoc.rb:

require 'github/markup'

puts GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, File.read('README.md'))

Akhirnya, aktifkan seperti ini:

ruby ./render-readme-for-javadoc.rb >> project/src/main/javadoc/overview.html

ETA: Ini tidak akan membantu Anda dengan StackOverflow-flavor Markdown, yang tampaknya gagal pada jawaban ini.


Saya pikir ini adalah jawaban "paling dekat dengan sumber" dari semuanya karena alat ini adalah yang digunakan oleh github.
memoselyk

3

Saya menggunakan Pandoc dengan opsi --from=gfmuntuk GitHub Flavoured Markdown seperti ini:

$ pandoc my_file.md   --from=gfm -t html -o my_file.html

Dengan Pandoc 1.16.0.2 di linux mint 18 saya mendapatkan error: pandoc: Unknown reader: gfm. Pergi ke 2.2.1 memperbaiki ini.
kidmose

Saya mengujinya dengan Pandoc 2.1.2.
Asme Just

cara menginstal 2.2.1 di ubuntu?
Alexander Mills

@AlexanderMills Sudahkah Anda mencoba sudo apt install pandoc?
Asme Just

2

Memperbaiki solusi @ barry-stae. Tempelkan cuplikan ini di ~ / .bashrc

function mdviewer(){
  pandoc $* | lynx -stdin
}

Kemudian kita dapat dengan cepat melihat file dari command-line. Juga bekerja dengan baik selama sesi SSH / Telnet.

mdviewer README.md

2

Penambahan terlambat tetapi showdownjs memiliki alat CLI yang dapat Anda gunakan untuk mem-parsing MD ke HTML.


1

Saya menemukan situs web yang akan melakukan ini untuk Anda: http://tmpvar.com/markdown.html . Tempel di Markdown Anda, dan itu akan menampilkannya untuk Anda. Tampaknya berfungsi dengan baik!

Namun, tampaknya tidak menangani opsi penyorotan sintaks untuk kode; artinya, ~~~rubyfitur tidak berfungsi. Itu hanya mencetak 'ruby'.


tmpvar tampaknya tidak melakukan peningkatan versi GFM seperti tabel
Greg

0

Meningkatkan pada @ barry-stae dan @Simpan jawaban untuk pengguna elinks biasa, Anda akan menambahkan yang berikut ini ke .bashrc:

function mdviewer() {
  pandoc $* | elinks --force-html
}

Jangan lupa untuk menginstal pandoc (dan elinks).


0

Berdasarkan jawaban Jim Lim , saya memasang permata GitHub Markdown. Itu termasuk skrip bernama gfm yang mengambil nama file pada baris perintah dan menulis HTML yang setara ke output standar. Saya memodifikasi sedikit untuk menyimpan file ke disk dan kemudian untuk membuka browser standar dengan launchy:

#!/usr/bin/env ruby

HELP = <<-help
  Usage: gfm [--readme | --plaintext] [<file>]
  Convert a GitHub-Flavored Markdown file to HTML and write to standard output.
  With no <file> or when <file> is '-', read Markdown source text from standard input.
  With `--readme`, the files are parsed like README.md files in GitHub.com. By default,
  the files are parsed with all the GFM extensions.
help

if ARGV.include?('--help')
  puts HELP
  exit 0
end

root = File.expand_path('../../', __FILE__)
$:.unshift File.expand_path('lib', root)

require 'github/markdown'
require 'tempfile'
require 'launchy'

mode = :gfm
mode = :markdown if ARGV.delete('--readme')
mode = :plaintext if ARGV.delete('--plaintext')

outputFilePath = File.join(Dir.tmpdir, File.basename(ARGF.path))  + ".html"

File.open(outputFilePath, "w") do |outputFile |
    outputFile.write(GitHub::Markdown.to_html(ARGF.read, mode))
end

outputFileUri = 'file:///' + outputFilePath

Launchy.open(outputFileUri)

1
Saya mencoba ini dengan blok berpagar untuk Ruby dan Mentimun. Meskipun pagar ( ruby, mentimun, dll.) Tampaknya dikenali sebagai pagar (karena dibuat dalam teks lebar tetap), tidak ada penyorotan sintaksis. Ada yang tahu kenapa?
Keith Bennett

0

Pendekatan 'cepat dan kotor' adalah mengunduh halaman HTML wiki menggunakan wgetutilitas, alih-alih mengkloningnya. Sebagai contoh, ini adalah bagaimana saya mengunduh wiki Hystrix dari GitHub (Saya menggunakan Ubuntu Linux):

 $ wget -e robots=off -nH -E -H -k -K -p https://github.com/Netflix/Hystrix/wiki
 $ wget -e robots=off -nH -E -H -k -K -I "Netflix/Hystrix/wiki" -r -l 1 https://github.com/Netflix/Hystrix/wiki

Panggilan pertama akan mengunduh halaman entri wiki dan semua dependensinya. Yang kedua akan memanggil semua sub-halaman di dalamnya. Anda dapat menelusuri sekarang wiki dengan membukaNetflix/Hystrix/wiki.1.html .

Perhatikan bahwa kedua panggilan wgetdiperlukan. Jika Anda hanya menjalankan yang kedua maka Anda akan kehilangan beberapa dependensi yang diperlukan untuk menampilkan halaman dengan benar.


-1

Baru-baru ini saya membuat apa yang Anda inginkan, karena saya perlu membuat dokumentasi dari file Markdown dan gaya GitHub cukup bagus. Cobalah. Itu ditulis dalam Node.js.

gfm


Saya tahu, modul ini belum selesai dalam 9 bulan, mengapa Anda menurunkan posting lama?
Gabriel Llamas
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.