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


106

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:


127

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.


8
Dzięki za podpowiedź „M”!
Jedidja,

2
Github Markdown Live Preview nie renderuje tabel ...
Rubens Mariuzzo,

2
Jeśli wolisz screencast wideo, stworzyłem jeden wyjaśniający Markdown tutaj: mikemclin.net/markdown-syntax-language
Mike McLin

2
@Mike McLin Świetne wideo wyjaśniające składnię i koncepcje stojące za nią! Świetne intro dla nowicjusza przecenionego, takiego jak ja :)
Brock

1
Wydaje się, że podgląd na żywo w Markdown również nie jest zgodny z regułami github dotyczącymi podkreślenia w środku słów, np. My_setup_script.py nie użyje kursywy 'setup' na githubie, ale w podglądzie . Jest to przydatne, ale tylko po to, żeby ludzie wiedzieli.
user2428107

11

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


5

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.

wprowadź opis obrazu tutaj

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

wprowadź opis obrazu tutaj

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


4

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 .

https://f.cloud.github.com/assets/17715/1999080/7f0c15a2-853e-11e3-95dc-1d7737e1ec20.png

Zmiany nietekstowe są wyświetlane z niskim klawiszem, kropkowanym podkreśleniem. Najedź kursorem na tekst, aby zobaczyć, co się zmieniło:

https://f.cloud.github.com/assets/17715/2005588/714cb5ea-86ef-11e3-9e92-a0d11ba6084f.png


1

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


1

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

wprowadź opis obrazu tutaj


0

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.

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.