Nie jestem zbyt zaznajomiony z lekkim językiem znaczników używanym przez github podczas aktualizowania plików README.
Gdzie są zasoby, które mogę przeczytać, jak napisać odpowiednią składnię znaczników dla plików README / wiki mojej biblioteki open source?
Czy istnieje narzędzie, które mogę „przeglądać dokumenty lokalnie w przeglądarce” przed wysłaniem zaktualizowanego pliku README do repozytorium na githubie?
Odpowiedzi:
Znacznik, o którym mowa, przypadkowo nazywa się Markdown i został stworzony przez Johna Grubera, autora bloga Daring Fireball . Oryginalne źródło Markdown można znaleźć w Daring Fireball - Markdown .
Istnieje wiele dialektów języka Markdown, dokumentację dotyczącą języka Github można znaleźć na stronie Github Flavored Markdown .
fajna wskazówka z tej strony:
naciśnij M na dowolnej stronie Github za pomocą edytora Markdown, aby wyświetlić ściągawkę.
Możesz także skorzystać ze strony Github Markdown Live Preview, aby przetestować swoje dokumenty Markdown.
Aktualizacja 2012-11-08 : Trwają prace nad standaryzacją składni Markdown. Zobacz przyszłość Markdown - Jeff Atwood, Coding Horror i W3C Markdown Community Group .
Aktualizacja 2014-09-09 : CommonMark został wydany standard przeceny i specyfikacja.
( Ponowne opublikowanie tej odpowiedzi z pewnymi zmianami).
Trochę za późno do gry, ale napisałem mały CLI w Pythonie. Nazywa się Grip (Github Readme Instant Preview) . Dodając do odpowiedzi Patryka, pozwoli ci to „przeglądać moje dokumenty lokalnie w mojej przeglądarce”.
Zainstaluj go za pomocą:
$ pip install grip
Aby go użyć, po prostu:
$ grip
Następnie odwiedź witrynę, localhost:5000aby wyświetlić readme.mdplik w tej lokalizacji.
Możesz również określić własny plik:
$ grip CHANGES.md
I zmień port:
$ grip 8080
Lub połącz dwa poprzednie:
$ grip CHANGES.md 8080
Możesz nawet renderować GitHub-Flavored Markdown (tj. Sposób renderowania komentarzy i problemów), opcjonalnie z kontekstem repozytorium do automatycznego hiperłącza do innych problemów:
$ grip --gfm --context=username/repo issue.md
Aby uzyskać zwięzłość, zapoznaj się z pozostałymi opcjami i ich szczegółami, korzystając z pomocy CLI:
$ grip -h
Istotne cechy:
Mam nadzieję że to pomoże. Sprawdź to .
Jest tutaj fajny edytor online / na żywo:
http://jbt.github.io/markdown-editor/
Jest też Previewprzycisk w GitHub.
Zobacz na poniższym zrzucie ekranu, że ten przycisk pojawia się, gdy kliknąłem opcję Edytuj README.md.
IMHO edytor na żywo jest lepszy niż obecny dostępny na GitHub.
AKTUALIZACJA
Właśnie teraz po wyszukaniu Markdowni Visual Studio stwierdziłem, że jeśli używasz VS, możesz zainstalować Web Essentials i uzyskać Markdownwsparcie bezpośrednio z Visual Studio. To super!
To ma:
Szczegóły na ten temat tutaj .
Zwróć uwagę, że od lutego 2014 r. Dzięki „ Rendered Prose Diffs ” możesz również zobaczyć wyrenderowaną wersję różnic w pliku przecen:
Zatwierdzenia i żądania ściągnięcia, w tym pliki prozy, zawierają teraz źródło i renderowane widoki .
Zmiany nietekstowe są wyświetlane z niskim klawiszem, kropkowanym podkreśleniem. Najedź kursorem na tekst, aby zobaczyć, co się zmieniło:
Inna opcja - nowy edytor tekstu Github, Atom, wyrenderuje przecenę o smaku github podczas edycji. Zobacz https://atom.io/
Nie jestem pewien, czy w dłuższej perspektywie będzie darmowy (jak w piwie).
Nie stwierdziłem, że inne narzędzia są wystarczająco dobre - chciałem:
Na tym ostatecznie zdecydowałem: 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.
Więc utworzyłem alias:
alias gm='gfms -a -p 8070'
Użycie tej -popcji trafia do API Github i używa aktualnego CSS Github, więc nie ma żadnych niespodzianek.