Arbeiten mit README.md auf github.com [geschlossen]

Ich bin nicht allzu vertraut mit der leichten Markup-Sprache, die Github beim Aktualisieren von README-Dateien verwendet.

Wo sind die Ressourcen, die ich lesen kann, um die entsprechende Markup-Syntax für die README / Wiki-Dateien meiner Open Source-Bibliothek zu schreiben?

Und gibt es ein Tool, mit dem ich "meine Dokumente lokal in meinem Browser überprüfen" kann, bevor ich die aktualisierte README-Datei in mein Github-Repository verschiebe?

Das fragliche Markup heißt zufällig Markdown und wurde von John Gruber, Autor des Daring Fireball-Blogs, erstellt . Die ursprüngliche Quelle von Markdown finden Sie unter Daring Fireball - Markdown .

Es gibt viele Markdown-Dialekte. Die Dokumentation zu Github finden Sie auf der Seite Github Flavored Markdown .

schöner Tipp von dieser Seite:

Presse M auf jeder Seite Github mit einem Markdown - Editor die Spickzettel zu offenbaren.

Sie können auch die Github Markdown Live-Vorschau- Seite verwenden, um Ihre Markdown-Dokumente zu testen.

Update 08.11.2012 : Es werden Anstrengungen unternommen, um die Markdown-Syntax zu standardisieren. Sehen Sie die Zukunft von Markdown - Jeff Atwood, Coding Horror und W3C Markdown Community Group .

Update 09.09.2014 : CommonMark hat einen Abschriftenstandard und eine Spezifikation veröffentlicht.

( Veröffentlichen Sie diese Antwort mit einigen Änderungen erneut.)

Ein bisschen spät zum Spiel, aber ich habe eine kleine CLI in Python geschrieben. Es heißt Grip (Github Readme Instant Preview) . Wenn Sie Patricks Antwort ergänzen, können Sie "meine Dokumente lokal in meinem Browser überprüfen".

Installieren Sie es mit:

$ pip install grip

Und um es zu benutzen, einfach:

$ grip

Besuchen Sie dann localhost:5000, um die readme.mdDatei an diesem Speicherort anzuzeigen .

Sie können auch Ihre eigene Datei angeben:

$ grip CHANGES.md

Und ändern Sie den Port:

$ grip 8080

Oder kombinieren Sie die beiden vorherigen:

$ grip CHANGES.md 8080

Sie können sogar GitHub-Flavored Markdown (dh wie Kommentare und Probleme gerendert werden) rendern, optional mit Repo-Kontext, um Verweise auf andere Probleme automatisch per Hyperlink zu verknüpfen:

$ grip --gfm --context=username/repo issue.md

Der Kürze halber sehen Sie sich die restlichen Optionen und ihre Details mithilfe der CLI-Hilfe an:

$ grip -h

Bemerkenswerte Eigenschaften:

• Rendert Seiten so, dass sie genau wie auf GitHub aussehen
• Eingezäunte Blöcke
• Python-API
• Navigieren Sie zwischen verknüpften Dateien
• Exportieren Sie ein gerendertes Dokument in eine Datei

Hoffe das hilft. Schau es dir an .

Hier gibt es einen netten Online- / Live-Editor:

http://jbt.github.io/markdown-editor/

Es gibt auch einen PreviewButton bei GitHub.

Im folgenden Screenshot sehen Sie, dass diese Schaltfläche angezeigt wird, wenn ich auf Bearbeiten geklickt habe README.md.

IMHO ist der Live- Editor besser als der aktuelle bei GitHub.

AKTUALISIEREN

Erst jetzt habe ich nach der Suche nach Markdownund Visual Studio festgestellt, dass Sie, wenn Sie VS verwenden, Web Essentials installieren und MarkdownUnterstützung direkt in Visual Studio erhalten können. Das ist cool!

Es hat:

• Syntaxhervorhebung => Vollständige Kolorierung für die Markdown-Syntax
• Intellisense für eingebettete Sprachen ( W00T ) => Die eingebettete Sprachfunktion von GitHub wird durch die Unterstützung der `` `Sprachsyntax vollständig unterstützt.

• Vorschaufenster => Ein nebeneinander angezeigtes Vorschaufenster des gerenderten HTML anzeigen
• In HTML kompilieren => Klicken Sie mit der rechten Maustaste auf eine Markdown-Datei und wählen Sie Markdown in HTML kompilieren. Dadurch wird eine HTML-Datei generiert, die unter der Markdown-Datei verschachtelt ist, und sie bleibt synchron, wenn sich die Markdown-Datei ändert.
• Benutzerdefiniertes Stylesheet => Sie können ein lösungsspezifisches Stylesheet hinzufügen, um die Stile des Vorschaufensters zu steuern.

Details dazu hier .

Beachten Sie, dass Sie seit Februar 2014 mit " Rendered Prose Diffs " auch die gerenderte Version eines Diff in einer Markdown-Datei sehen können:

Commits und Pull-Anfragen, einschließlich Prosadateien, enthalten jetzt Quell- und gerenderte Ansichten .

Nicht-Text-Änderungen werden mit einer zurückhaltenden, gepunkteten Unterstreichung angezeigt. Bewegen Sie den Mauszeiger über den Text, um zu sehen, was sich geändert hat:

Eine weitere Option: Der neue Texteditor von Github, Atom, rendert beim Bearbeiten Markdowns mit Github-Geschmack. Siehe https://atom.io/

Ich bin mir nicht sicher, ob es langfristig kostenlos sein wird (wie bei Bier).

Ab heute können Sie eine Vorschau anzeigen, während Sie die Datei bearbeiten.

Ich fand nicht, dass die anderen Werkzeuge gut genug waren - ich wollte:

1. Möglichkeit, offline zu bearbeiten
2. Nicht nur regulärer Abschlag, sondern auch der eigentliche Abschlag mit Github-Geschmack

Darauf habe ich mich letztendlich festgelegt: 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.

Also habe ich Aliasing:

alias gm='gfms -a -p 8070'

Wenn Sie die -pOption verwenden, wird die Github-API aufgerufen und das aktuelle Github-CSS verwendet, sodass keine Überraschungen auftreten.