Co to jest plik README „sformatowany w dół” w Github?

27

Nie jest dla mnie jasne, jaki jest format, czy istnieją systematyczne / wiersza polecenia wymagania dotyczące jego tworzenia itp.

Zasadniczo wystarczy znać specyfikacje i czy istnieją techniczne kroki do wygenerowania pliku README.

github błędy
źródło
4
Nie, tylko plik tekstowy, który edytujesz ręcznie. Jeśli chodzi o składnię, en.wikipedia.org/wiki/Markdown
Andrea
3
to ten sam format edycji wiki, którego używa ta strona.
k3b
+1 @Andrea: Dzięki, chociaż mogę wymyślić więcej niż kilka formatów obniżki cen, jaki format i wersja jest oczekiwana w Github? Komentujesz również jako więcej odpowiedzi, prześlij ją jako pełną odpowiedź. Jeszcze raz dzięki!
błąka się
+1 @ K3b: Czy wierzysz, że coś masz na myśli, czy mówisz o używaniu Golluma przez Golluma , co na przykład umożliwia względne łączenie? Jeśli tak, proszę opublikować to jako odpowiedź, ponieważ uważam, że to poprawna odpowiedź. Dzięki!
błądzi

Odpowiedzi:

37

Markdown to prosta składnia zapewniająca informacje semantyczne i reprezentująca wspólne formatowanie w postaci zwykłego tekstu. Daring Fireball ma niesamowity przewodnik po składni dla standardowego markdown . Następnie GitHub używa wariantu tego, który nazywają GdownHub Flavored Markdown .

Aby skonfigurować plik Readme, po prostu utwórz zwykły plik tekstowy i nazwij go README (lub README.md / README.markdown) i zatwierdz go do katalogu głównego repozytorium. GitHub pobierze to jako plik Readme projektu.

Kim Burgess
źródło
2
Stworzyłem również wideo wyjaśniające, jak korzystać z Markdown. Można go znaleźć tutaj: mikemclin.net/markdown-syntax-language
Mike McLin
9

Wikipedia - Markdown odwołuje się do strony „GitHub Flavored Markdown - Wprowadzenie” ( archiwum )

Cytat ze strony:

GitHub używa tego, co nazywamy „GitHub Flavored Markdown” (GFM) do wiadomości, problemów i komentarzy. Różni się on od standardowego Markdown (SM) na kilka istotnych sposobów i dodaje dodatkowe funkcje.

Strona zawiera także opis różnic w stosunku do standardowego Markdown.

Jest też więcej informacji o tym, jak Markdown jest renderowany przez GitHub:

Jeśli interesuje Cię sposób renderowania plików Markdown, możesz wypróbować Redcarpet , nasz interfejs Ruby do biblioteki Sundown .

(Najwyraźniej Sundown jest rzeczywistym parserem Markdown, który jest używany za zasłonami).

Aby dodać jeszcze jedną warstwę abstrakcji, Sundown jest rozwidleniem nawet innego parsera Markdown :-)
Cytat ze strony Sundit na GitHubie :

Sundown to parser Markdown oparty na oryginalnym kodzie biblioteki Upskirt autorstwa Natacha Porté.

Christian Specht
źródło
1

To bardzo dziwne, ale wygląda na to, że GitHub nie używa GdownHub-Flavored Markdown (GFM) podczas renderowania pliku README.

GitHub używa „GitHub Flavored Markdown” lub GFM w całej witrynie - w kwestiach, komentarzach i żądaniach ściągania.

Zamiast tego wydaje się, że używa wersji o nazwie redcarpet jako część projektu znaczników GitHub . Obsługują również kilka innych formatów znaczników, w tym MediaWiki. Wystarczy użyć odpowiedniego rozszerzenia pliku, a GitHub wyświetli znaczniki.

Jeśli chcesz zobaczyć różnice między dwoma różnymi smakami Markdown, przeczytaj opis GFM i jego dodatkowych funkcji .

Don Kirkby
źródło
1
Redcarpet i Github Flavored Markdown to dwie odrębne, ale uzupełniające się koncepcje, nie konkurujące ze sobą implementacje tego samego. redcarpet jest po prostu kompilator , który bierze rzeczy napisane w Github Smakowe Markdown języka i wyjścia HTML lub XHTML.
8bittree