Praca z README.md na github.com [zamknięte]

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?

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:

• Renderuje strony tak, aby wyglądały dokładnie tak, jak w GitHub
• Bloki ogrodzone
• Python API
• Nawiguj między połączonymi plikami
• Eksportuj renderowany dokument do pliku

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:

• Podświetlanie składni => Pełna kolorystyka składni Markdown
• Intellisense dla języków osadzonych ( W00T ) => Funkcja języka osadzonego GitHub jest w pełni obsługiwana przez obsługę składni języka ``.

• Okno podglądu => Zobacz obok siebie okno podglądu renderowanego kodu HTML
• Kompiluj do HTML => Kliknij prawym przyciskiem myszy dowolny plik Markdown i wybierz Kompiluj Markdown do HTML. Spowoduje to wygenerowanie pliku .html zagnieżdżonego w pliku Markdown i pozostanie zsynchronizowany, gdy plik Markdown się zmieni.
• Niestandardowy arkusz stylów => Możesz dodać arkusz stylów specyficzny dla rozwiązania, aby kontrolować style okna podglądu.

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).

Od dzisiaj możesz wyświetlać podgląd podczas edycji pliku.

Nie stwierdziłem, że inne narzędzia są wystarczająco dobre - chciałem:

1. Możliwość edycji offline
2. Nie tylko zwykłe przeceny, ale faktyczne przeceny o smaku Github

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.