Czy istnieje narzędzie wiersza polecenia do renderowania Markdown o smaku GitHub?


414

Zastanawiam się, czy istnieje narzędzie wiersza polecenia do pobierania pliku Markdown o smaku GitHub i renderowania go w formacie HTML.

Używam wiki GitHub do tworzenia treści na stronie. Sklonowałem repozytorium na moim serwerze i chciałbym następnie przetworzyć je na zwykły kod HTML. Ważne jest dla mnie, że to, co pojawia się na GitHub, jest dokładnie tak, jak powinno wyglądać moja strona internetowa. Bardzo chciałbym również używać bloków ogrodzonych ~~~, więc wolałbym nie używać tylko standardowej składni Markdown.

Zajrzałem trochę do podglądu na żywo JavaScript, myśląc, że mógłbym podłączyć go do Node.js, ale mówią, że jest przestarzały. Przeglądałem repozytorium redcarpet, ale nie wygląda na to, żeby miało interfejs wiersza poleceń.

Rzuciłem jednak swoje własne rozwiązanie, ponieważ żadne rozwiązanie tutaj nie jest wyraźnie lepsze od innych, pozostawię pytanie bez wybranej odpowiedzi.


2
RE: AKTUALIZACJA: Jeśli dodam --outargument do uchwycenia w celu renderowania do pliku HTML zamiast przeglądarki, czy byłoby to dopuszczalne?
Joe

@ Joe proszę dodać tę opcję!
bguiz

@McLeopold @bguiz właśnie wdrożył --exportopcję, która renderuje GFM i jego style w jednym pliku. Czy to odpowiada na pytanie?
Joe

3
@ McLeopold, Joe w pewnym sensie znokautował to z parku, tworząc proste rozwiązanie wielokrotnego użytku, może chcieć dać mu odpowiedź.
James McMahon

1
Sam Github używa Sundown . Zobacz stackoverflow.com/a/7694931/632951
Pacerier

Odpowiedzi:


447

Napisałem mały CLI w Pythonie i dodałem obsługę GFM. Nazywa się Grip (Github Readme Instant Preview) .

Zainstaluj z:

$ pip install grip

Aby z niego skorzystać, po prostu:

$ grip

Następnie odwiedź, localhost:5000aby wyświetlić readme.mdplik w tej lokalizacji.

Możesz także określić własny plik:

$ grip CHANGES.md

I zmień port:

$ grip 8080

I, oczywiście, specjalnie renderuj Markdown o smaku GitHub, opcjonalnie z kontekstem repozytorium:

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

Ważne funkcje:

  • Renderuje strony tak, aby wyglądały dokładnie tak, jak na GitHub
  • Ogrodzone bloki
  • Python API
  • Nawiguj między połączonymi plikami (dzięki, vladwing !) Dodanymi w wersji 2.0
  • Eksport do jednego pliku (dzięki, iliggio !) Dodanego w wersji 2.0
  • Nowość: odczyt stdini eksport do stdout dodanego w 3.0

Mam nadzieję, że to pomoże komuś tutaj. Sprawdź to .


1
Działa naprawdę dobrze i nie można pobić łatwości instalacji Pythonistas!
RichVel

29
To powinien być pierwszy hit dla „podglądu github przeceny”. Wszystko inne jest skomplikowane, nie działa lub nie obsługuje wszystkich funkcji GitHub. gripdziała od razu po wyjęciu z pudełka.
Bluu

1
@Houdini Ten problem jest nieaktualny. Flask obsługuje 3.3, patrz flask.pocoo.org/docs/python3 . Oto najnowszy wątek Github na temat github.com/mitsuhiko/flask/issues/587 . Jeśli istnieje inna zależność, która wymaga aktualizacji, możesz otworzyć problem lub żądanie ściągnięcia.
Joe

3
Należy zauważyć, że ten pakiet wymaga aktywnego połączenia internetowego i danych uwierzytelniających github (podanych w wierszu poleceń), jeśli wykonasz więcej niż 60 odświeżeń na godzinę.
leo

13
Jak wspomniano wcześniej, nie sądzę, że jest to szczególnie świetne rozwiązanie, ponieważ wszystko, co robi, idzie do Github i powoduje, że Github renderuje Twój Markdown. Wymaga działającego połączenia internetowego z dostępem do Github, a jeśli Github umrze, to narzędzie przestanie działać. Wolę mieć rozwiązanie całkowicie offline.
Jez

114

Nie znalazłem szybkiej i łatwej metody dla Markdown o smaku GitHub, ale znalazłem nieco bardziej ogólną wersję - Pandoc . Konwertuje z / do wielu formatów, w tym Markdown, Rest, HTML i innych.

Opracowałem również plik Makefiledo konwersji wszystkich plików .md do .html (w dużej części do przykładu w Writing, Markdown i 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
Używam „Watch Pandoc ...” do ciągłej konwersji pliku Markdown do HTML, a chromowane rozszerzenie „Live Reload”, aby uzyskać w czasie rzeczywistym funkcję „zostań tam, gdzie też jestem przewinięty”, i działa świetnie . chrome.google.com/webstore/detail/livereload/…
Brad Parks

1
Pandoc dobrze odczytuje GFM, ale nie generuje tego samego kodu HTML, co GitHub - na przykład, jeśli masz <pre/>źródło wieloliniowe w źródle GFM, Pandoc umieści w nim <br/>tagi podziałów linii, podczas gdy renderer GitHub, chociaż usuwa wiodące białe znaki, w przeciwnym razie wydaje się pozostawić treść w spokoju.
David Moles,

1
Jak można uzyskać ładną stylizację na wynikowym HTML? Moje wyniki wciąż są renderowane na przykład w Times New Roman.
Holistic Developer

Instrukcje instalacji Pandoc są tutaj . W systemie macOS:brew install pandoc
Master of Ducks,

1
ani format wejściowy ani gfmani markdown_githubpoprawnie nie renderują takich elementów jak bloki kodu.
user5359531,

29

Może to może pomóc:

gem install github-markdown

Nie istnieje żadna dokumentacja, ale mam ją z dokumentacji gollum . Patrząc na rubydoc.info , wygląda na to, że możesz użyć:

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

w twoim kodzie Ruby. Możesz to łatwo zawinąć w skrypt, aby zamienić go w narzędzie wiersza poleceń:

#!/usr/bin/env ruby

# render.rb
require 'github/markdown'

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

Wykonaj to za pomocą ./render.rb path/to/my/markdown/file.md. Należy pamiętać, że nie jest to bezpieczne do użycia w produkcji bez odkażania.


1
Dzięki Jim, z powodu praktycznie nieistniejących przykładów, utknąłem przy wymaganym kroku (zastąpienie kreski kreską sprawiło, że to zrobiło) ..;)
plesatejvlk

Jest to świetne, jeśli już używasz NPM. Musiałem go użyć, ponieważ DOxygen powodował ciągłe problemy ze specjalnie obniżoną ceną github + eksport do HTML.
kayleeFrye_onDeck

czy działa to lokalnie, czy wysyła dane do API GitHub?
user5359531,

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

Nie obsługuje rozszerzeń GitHub, ale jest lepszy niż nic. Wierzę, że możesz rozszerzyć moduł, aby obsługiwał dodatki GitHub.


1
/ usr / bin / python: markdown to pakiet, którego nie można bezpośrednio wykonać
Kazimieras Aliulis,

2
Proste wyjście HTML bez wymyślnych tagów.
Halil Kaskavalci,

23

Prawdopodobnie nie to, czego chcesz, ale ponieważ wspomniałeś o Node.js: nie mogłem znaleźć dobrego narzędzia do podglądania dokumentacji GitHub Flavored Markdown na moim dysku lokalnym przed przekazaniem ich do GitHub, więc dzisiaj stworzyłem jedną, opartą na Node.js: https : //github.com/ypocat/gfms

Być może możesz użyć ponownie pliku showdown.js na swojej Wiki, jeśli twoje pytanie jest nadal aktualne. Jeśli nie, być może inne osoby, które borykają się z tym samym problemem, co ja, znajdą (tak jak ja) to pytanie i odpowiedź na nie.


Dobra robota, stary. Oszczędza mi to konieczności uciekania się do Ruby lub Pythona, gdy piszę aplikację węzłową, co jest świetne.
jedd.ahyoung

19

Aby odczytać plik README.md w terminalu, którego używam:

pandoc README.md | lynx -stdin

Pandoc wysyła go w formacie HTML, który Lynx renderuje w twoim terminalu.

Działa świetnie: wypełnia mój terminal, skróty są pokazane poniżej, mogę przewijać, a linki działają! Jest tylko jeden rozmiar czcionki, ale rekompensują to kolory + wcięcie + wyrównanie.

Instalacja:

sudo apt-get install pandoc lynx

1
Pytanie dotyczy w szczególności użycia wiersza polecenia. Przed napisaniem własnego skryptu ruby ​​(lub serwera węzła egad) daj temu szansę.
Cora Middleton,

Dokładnie działa to w twoim terminalu. Lub jeśli twoja ulubiona przeglądarka (na komputerze?) Może uzyskać dostęp do tego folderu pandoc readme.md -o readme.md.htmli otworzyć wynikowy plik.
Barry Staes

@ baerry-staes Tak, przepraszam, mam nadzieję, że było jasne, że Twoja była moją ulubioną odpowiedzią.
Cora Middleton,

@JustinMiddleton tak, mam to, dziękuję. Mój komentarz polegał na dodaniu dodatkowych informacji dla użytkowników komputerów stacjonarnych. Pomyślałem, że ktoś kiedyś to przeczyta, może to być przydatne.
Barry Staes

1
Wypróbowałem około 5-6 innych czytników konsolowych i jest to zdecydowanie najlepsze rozwiązanie. Właśnie dodałem najbardziej podstawową funkcję do mojej konfiguracji, aby była nieco szybsza w użyciu. function md { pandoc $@ | lynx -stdin }
Russ Brown

17

GitHub ma API Markdown, którego możesz użyć.


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

@VebjornLjosa * that * or grip... Ty wybrałeś. : P
yyny

13

Użyj zaznaczonego . Obsługuje GitHub Flavored Markdown, może być używany jako moduł Node.js i z wiersza poleceń.

Przykładem może być:

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

1
Zauważyłem, że nie obsługuje to takich funkcji, jak podświetlanie składni bloków kodu i nowsze funkcje, takie jak listy kontrolne. Ale hej, robi się to przez większość czasu!
bguiz

Bardzo miło, jedyne, czego mi brakuje, to granice stołów. Cóż, przynajmniej mogę je w ogóle renderować, to jest dokładnie to, czego potrzebuję.
Włącz

Nie jestem pewien co do tego przykładu, co to jest ^D?
Matthew

10

Jest to głównie kontynuacja odpowiedzi @ barry-staes na użycie Pandoc . Homebrew ma to również, jeśli jesteś na komputerze Mac:

brew install pandoc

Pandoc obsługuje GFM jako format wejściowy poprzez markdown_githubnazwę.

Dane wyjściowe do pliku

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

Otwórz w Lynx

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

Otwórz w domyślnej przeglądarce w systemie OS X

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

Integracja TextMate

Zawsze możesz potokować bieżący wybór lub bieżący dokument do jednego z powyższych, jak pozwala na to większość edytorów. Możesz także łatwo skonfigurować środowisko, aby pandoczastępowało domyślny procesor Markdown używany przez pakiet Markdown .

Najpierw utwórz skrypt powłoki z następującą zawartością (zadzwonię ghmarkdown):

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

Następnie możesz ustawić TM_MARKDOWNzmienną (w Preferencjach → Zmienne) na /path/to/ghmarkdown, i zastąpi ona domyślny procesor Markdown.


10

Stworzyłem narzędzie podobne do funkcji podglądu Atom, ale jako samodzielna aplikacja. Nie jestem pewien, czy tego właśnie szukasz, ale może być pomocny. - https://github.com/yoshuawuyts/vmd

Vmd


Nadal to popieracie? Próbowałem dzisiaj zainstalować z NPM, ale nie ma kości. > pobieranie electron-v0.36.9-win32-x64.zip> Błąd: certyfikat z podpisem własnym
kayleeFrye_onDeck

1
Tak, jesteśmy! Na jakiej wersji npm / node uruchomiłeś to? - zachęcamy do otwarcia problemu dotyczącego GH, a my przyjrzymy się temu. Dzięki!
Yoshua Wuyts

8

pandocz browserdziała dla mnie dobrze.

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

Instalacja (Zakładając, że używasz Mac OSX):

  • $ brew install pandoc

  • $ brew install browser

Lub na Debian / Ubuntu: apt-get install pandoc browser


1
apt-get isntall pandoczrobi, nie trzeba używać niepewnych, lokalnych rzeczy, takich jak napar.
Dominik George

1
@DominikGeorge jest literówka, jest instalowana , a nie isntall
Federico

11
@DominikGeorge nie ma apt-get na macOS.
richrad

6

Zobacz także https://softwareengineering.stackexchange.com/a/128721/24257 .


Jeśli interesuje Cię sposób, w jaki [Github] renderuje pliki Markdown, możesz wypróbować Redcarpet , nasz interfejs Ruby do biblioteki Sundown.

Skrypt Ruby, który korzysta z Redcarpet , będzie „narzędziem wiersza poleceń”, jeśli będziesz mieć lokalnego Ruby


Nie mam pomysłów - nie piszę w Ruby i nie czytałem źródeł Redcarpet
Lazy Badger

@LazyBadger, Sundown jest faktycznym parserem (napisanym w C). Redcarpet nie jest potrzebny.
Pacerier

6

Opierając się na tym komentarzu , napisałem jedno-linijkę, aby trafić do Github Markdown API przy użyciu curli jq.

Wklej tę funkcję bash do wiersza poleceń lub do ~/.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"
}

A następnie, aby zobaczyć renderowany HTML uruchomiony w przeglądarce:

mdsee readme.md

Wymień open "$HTMLFILE"się lynx "$HTMLFILE"jeśli potrzebujesz czystego roztworu terminala.


4

GitHub (od tego czasu) opracował ładny modułowy edytor tekstów o nazwie Atom (oparty na Chromium i używa modułów Node.js do pakietów).

Domyślnie preinstalowany pakiet Podgląd Markdown umożliwia wyświetlanie podglądu w osobnej zakładce za pomocą Ctrl+ Shift+ M.

Nie testowałem jej pełnej składni, ale ponieważ pochodzi ona z GitHub, byłbym bardzo zaskoczony, gdyby składnia podglądu była inna niż ich (blokowanie ogrodzeń przy użyciu ~~~pracy).

Teraz, chociaż technicznie nie jest oparty na wierszu poleceń, używa Node.js i wyświetla dane wyjściowe do renderera opartego na DOM , co może pomóc każdemu, kto próbuje renderować HTML oparty na składni GitHub na serwerze internetowym opartym na Node.js, lub po prostu edytować / jego plik README.md offline.


1
W Atom możesz zainstalować pakiet o nazwie gfm-pdf ( atom.io/packages/gfm-pdf ), który eksportuje twój dokument przeceny do dokumentu HTML i / lub PDF. Wymagana jest biblioteka wkhtmltopdf .
spren9er,


3

Istnieje naprawdę ładne i proste narzędzie do przeglądania dokumentów GFM Markdown:

GFMS - Github Flavored Markdown Server

Jest to prosty i lekki (nie wymaga konfiguracji) serwer HTTP, który możesz uruchomić w dowolnym katalogu zawierającym pliki Markdown, aby je przeglądać.

Funkcje:

  • Pełna obsługa GFM Markdown
  • Podświetlanie składni kodu źródłowego
  • Przeglądanie plików i katalogów
  • Ładnie wyglądający wynik (i konfigurowalne arkusze stylów CSS)
  • Eksportuj do pliku PDF

3

W tym celu udało mi się użyć jednowierszowego skryptu Ruby (chociaż musiał on znajdować się w osobnym pliku). Najpierw uruchom te polecenia raz na każdym komputerze klienckim, z którego będziesz wypychać dokumenty:

gem install github-markup
gem install commonmarker

Następnie zainstaluj ten skrypt na obrazie klienta i nazwij go render-readme-for-javadoc.rb:

require 'github/markup'

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

Na koniec wywołaj to w ten sposób:

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

ETA: To nie pomoże ci w StackOverflow-flavour Markdown, który wydaje się zawodzić w tej odpowiedzi.


Myślę, że jest to odpowiedź „najbliższa źródła” ze wszystkich, ponieważ narzędzia te są używane przez github.
memoselyk

3

Używam Pandoc z opcją --from=gfmGitHub Flavored Markdown w następujący sposób:

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

Z pandoc 1.16.0.2 na Linux Mint 18 pojawia się błąd: pandoc: Unknown reader: gfm. Przejście do 2.2.1 naprawia to.
kidmose

Testowałem to z Pandoc 2.1.2.
Asme Just

jak zainstalować 2.2.1 na Ubuntu?
Alexander Mills,

@AlexanderMills Próbowałeś sudo apt install pandoc?
Asme, tylko

2

Poprawa rozwiązania @ barry-stae. Wklej ten fragment w ~ / .bashrc

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

Następnie możemy szybko wyświetlić plik z wiersza poleceń. Działa również ładnie w sesjach SSH / Telnet.

mdviewer README.md


1

Znalazłem stronę internetową, która zrobi to za Ciebie: http://tmpvar.com/markdown.html . Wklej swoje Markdown, a wyświetli się dla ciebie. Wygląda na to, że działa dobrze!

Wydaje się jednak, że nie obsługuje opcji podświetlania składni kodu; oznacza to, że ~~~rubyfunkcja nie działa. Po prostu drukuje „rubin”.


Wydaje się, że tmpvar nie wprowadza ulepszeń wersji GFM, takich jak tabele
Greg

0

Poprawiając odpowiedzi na @ barry-stae i @Sandeep dla zwykłych użytkowników elinks, dodałbyś następujące .bashrc:

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

Nie zapomnij zainstalować pandoc (i elinks).


0

Na podstawie odpowiedzi Jima Lima zainstalowałem klejnot GitHub Markdown. Obejmuje to skrypt o nazwie gfm, który pobiera nazwę pliku w wierszu poleceń i zapisuje równoważny kod HTML na standardowe wyjście. Zmodyfikowałem to nieco, aby zapisać plik na dysku, a następnie otworzyć standardową przeglądarkę z uruchomieniem:

#!/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
Próbowałem tego z ogrodzonymi blokami dla Ruby i Cucumber. Chociaż ogrodzenia ( ruby, ogórki itp.) Wydają się być rozpoznawane jako ogrodzenia (ponieważ są renderowane w tekście o stałej szerokości), nie ma podświetlania składni. Masz pomysł, dlaczego?
Keith Bennett

0

Podejście „szybkie i brudne” polega na pobraniu stron HTML wiki za pomocą wgetnarzędzia, zamiast klonowania. Na przykład w ten sposób pobrałem wiki Hystrix z GitHub (używam 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

Pierwsze wywołanie spowoduje pobranie strony wejściowej wiki i wszystkich jej zależności. Drugi wywoła na nim wszystkie podstrony. Możesz teraz przeglądać wiki, otwierając Netflix/Hystrix/wiki.1.html.

Pamiętaj, że oba połączenia z wgetsą konieczne. Jeśli po prostu uruchomisz drugi, stracisz pewne zależności wymagane do prawidłowego wyświetlania stron.


-1

Niedawno zrobiłem, co chcesz, ponieważ potrzebowałem wygenerować dokumentację z plików Markdown, a styl GitHub jest całkiem niezły. Spróbuj. Jest napisany w Node.js.

gfm


Wiem, że moduł nie został ulepszony w ciągu 9 miesięcy, dlaczego głosujesz na stary post?
Gabriel Llamas,
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.