Was ist eine "abschriftenformatierte" README-Datei auf Github?

27

Mir ist nicht klar, wie das Format lautet, ob es systematische / Befehlszeilenanforderungen für die Erstellung usw. gibt.

Grundsätzlich müssen Sie nur die technischen Daten kennen und wissen, ob es technische Schritte zum Generieren der README-Datei gibt.

github Fehler
quelle
4
Nein, nur eine Textdatei, die Sie von Hand bearbeiten. Was die Syntax betrifft
Andrea
3
Es ist dasselbe Wiki-Bearbeitungsformat, das diese Seite verwendet.
k3b
+1 @Andrea: Danke, obwohl ich an mehr als eine Handvoll Abschriftenformate denken kann, welches Format und welche Version wird für Github erwartet? Außerdem liest sich Ihr Kommentar eher als Antwort, bitte posten Sie ihn als vollständige Antwort. Noch einmal Danke!
Fehler
+1 @ K3b: Glaubst du, du hast etwas vor ? Sprichst du über Githubs Verwendung von Gollum , das zum Beispiel relative Verknüpfungen ermöglicht? Wenn ja, posten Sie dies bitte als Antwort, da ich glaube, dass dies die richtige Antwort ist. Vielen Dank!
Fehler

Antworten:

37

Markdown ist eine einfache Syntax zum Bereitstellen von semantischen Informationen und zum Darstellen allgemeiner Formatierungen in Klartext. Daring Fireball hat eine großartige Syntaxanleitung für Standard-Markdowns . GitHub verwendet dann eine Variante davon, die sie GitHub Flavored Markdown nennen .

Zum Einrichten Ihrer Readme-Datei erstellen Sie einfach eine Nur-Text-Datei, nennen Sie sie README (oder README.md / README.markdown) und schreiben Sie sie in das Stammverzeichnis Ihres Repos. GitHub wird dies dann als Projekt-Readme aufgreifen.

Kim Burgess
quelle
2
Ich habe auch ein Video erstellt, in dem erklärt wird, wie Markdown verwendet wird. Sie finden es hier: mikemclin.net/markdown-syntax-language
Mike McLin
9

Wikipedia - Markdown verweist auf die Seite "GitHub Flavored Markdown - Introduction" ( archv. )

Zitat von der Seite:

GitHub verwendet das, was wir "GitHub Flavored Markdown" (GFM) nennen, für Nachrichten, Probleme und Kommentare. Es unterscheidet sich von Standard Markdown (SM) in einigen wesentlichen Punkten und fügt einige zusätzliche Funktionen hinzu.

Die Seite enthält auch eine Beschreibung der Unterschiede zu Standard Markdown.

Es gibt auch mehr Informationen darüber, wie Markdown von GitHub tatsächlich gerendert wird:

Wenn Sie daran interessiert sind, wie wir Markdown-Dateien rendern, sollten Sie Redcarpet , unsere Ruby-Schnittstelle zur Sundown- Bibliothek , ausprobieren .

(Anscheinend ist Sundown der eigentliche Markdown-Parser, der hinter den Vorhängen verwendet wird.)

Um eine weitere Abstraktionsebene hinzuzufügen, ist Sundown eine Abzweigung eines weiteren Markdown-Parsers :-)
Zitat aus Sundowns GitHub-Seite :

Sundown ist ein Markdown-Parser, der auf dem Originalcode der Upskirt- Bibliothek von Natacha Porté basiert .

Christian Specht
quelle
1

Es ist sehr seltsam, aber es sieht so aus, als würde GitHub beim Rendern einer README-Datei kein GitHub-Flavored Markdown (GFM) verwenden.

GitHub verwendet "GitHub Flavored Markdown" oder GFM auf der gesamten Site - bei Problemen, Kommentaren und Pull-Anfragen.

Stattdessen scheint es eine Version namens redcarpet als Teil des GitHub-Markup-Projekts zu verwenden . Sie unterstützen auch mehrere andere Markup-Formate, einschließlich MediaWiki. Verwenden Sie einfach die richtige Dateierweiterung und GitHub rendert das Markup.

Wenn Sie die Unterschiede zwischen den beiden verschiedenen Varianten von Markdown sehen möchten, lesen Sie die Beschreibung von GFM und seinen zusätzlichen Funktionen .

Don Kirkby
quelle
1
redcarpet und Github Flavored Markdown sind zwei getrennte, aber sich ergänzende Konzepte, die keine konkurrierenden Implementierungen derselben Sache sind. redcarpet ist im Grunde ein Compiler , der in der Github aromatisiert Abschriften geschrieben Dinge nimmt Sprache und Ausgänge HTML oder XHTML.
8bittree