Ich habe ein Projekt zusammen mit mehreren Personen und wir haben eine README.md
Datei mit einer Reihe von GitHub Flavored Markdown, die auf unserer GitHub-Seite gerendert wird. Wir haben auch einen GitHub Pages-Zweig eingerichtet, der unter der Subdomain unserer GitHub-Organisation gehostet wird, und den automatischenREADME.md
Seitengenerator verwendet, der beim Erstellen unserer Seite einfach in unsere Datei geladen wird. Ich stelle jedoch fest, dass beim Aktualisieren unserer README.md
Datei die Projektseite nicht aktualisiert wird. Stattdessen müssen wir zur Registerkarte GitHub-Einstellungen gehen und die Projektseite neu erstellen und die README.md
Datei dabei neu laden .
Nachdem Sie die relative Verknüpfung zwischen Dokumentationsdateien auf den GitHub-Projektverzeichnisseiten gelesen haben . Ich mag den Abschlag sehr, da er viel Zeit spart, da wir nicht den gesamten HTML-Code für unsere Dokumentation von Hand schreiben müssen. Was ich jedoch möchte, ist, dass ich eine README.md
Datei haben kann, die relative Links zu anderen Dokumentationsdateien enthält, die sich unter befinden docs/*.md
. Ich hatte gehofft, dass es eine einfache Lösung gibt, damit meine anderen Dokumentationsdateien auch in meinem Gh-Pages-Zweig enthalten sind und unter meiner GitHub Pages-Subdomain gehostet und gerendert und / oder thematisiert werden.
Mit anderen Worten, meine Fragen sind:
- Gibt es eine Möglichkeit, meine README.md-Datei automatisch auf meiner Github Page-Subdomain zu aktualisieren?
- [BEARBEITEN]: Nein scheint die Antwort zu sein, wenn der automatische Seitengenerator verwendet wird. Sie müssen die Einstellungsseite für das Repo aufrufen und es bei jeder Änderung neu laden, um es zu aktualisieren.
- [BEARBEITEN]: Nein scheint die Antwort zu sein, wenn der automatische Seitengenerator verwendet wird. Sie müssen die Einstellungsseite für das Repo aufrufen und es bei jeder Änderung neu laden, um es zu aktualisieren.
- Gibt es eine Möglichkeit, meine relativen Links zu meiner Dokumentation in meiner README.md-Datei auf meinen Github-Seiten funktionieren zu lassen, vielleicht meine
/docs/*.md
mit meinen Github-Seiten zu synchronisieren und sie irgendwie zu rendern und / oder zu thematisieren?- [EDIT]: Von dem, was ich da schreibt diese Frage gelernt habe , scheint es , dass dies auf GitHub Seiten durch die Verwendung eines nur möglich ist , statische Website - Generator wie die Ruby Gem Jekyll und wahrscheinlich einige Verwendungen der webhooks von GitHub unterstützt , die erwähnt werden in den Kommentaren unten. Ich versuche gerade, eine optimale Lösung zu finden.
- [EDIT]: Von dem, was ich da schreibt diese Frage gelernt habe , scheint es , dass dies auf GitHub Seiten durch die Verwendung eines nur möglich ist , statische Website - Generator wie die Ruby Gem Jekyll und wahrscheinlich einige Verwendungen der webhooks von GitHub unterstützt , die erwähnt werden in den Kommentaren unten. Ich versuche gerade, eine optimale Lösung zu finden.
- Besser noch, gibt es eine noch einfachere Möglichkeit, dies zu tun und vielleicht nur eine Kopie meiner README.md und Dokumentation zu haben, die sowohl auf gh-Seiten als auch in meinem Hauptzweig verwendet wird und alles einfacher macht?
- [EDIT]: Es scheint, dass dies fast definitiv ein Nein ist. Ich habe über die Möglichkeit nachgedacht, etwas in GitHub zu integrieren, um dies zu ermöglichen. Es scheint, dass in Zukunft eine bessere Unterstützung für solche Dinge in GitHub Pages eingebaut werden könnte, oder zumindest hoffe ich definitiv, dass dies der Fall sein wird.
- [EDIT]: Es scheint, dass dies fast definitiv ein Nein ist. Ich habe über die Möglichkeit nachgedacht, etwas in GitHub zu integrieren, um dies zu ermöglichen. Es scheint, dass in Zukunft eine bessere Unterstützung für solche Dinge in GitHub Pages eingebaut werden könnte, oder zumindest hoffe ich definitiv, dass dies der Fall sein wird.
quelle
README.md
Version in GitHub-Seiten überträgt?gh-pages
.Antworten:
Ich werde eine von mir eingerichtete Lösung veröffentlichen, die die Tatsache ausnutzt, dass GitHub Pages Jekyll bereits mit dem automatischen Seitengenerator verwendet.
git checkout gh-pages
mkdir _layouts
mv index.html _layouts
git checkout master -- README.md
mv README.md index.md
index.md
Sie müssen die
index.html
Datei auch öffnen und die folgenden Änderungen vornehmen:Entfernen Sie den gerenderten HTML-Code aus dem Markdown in Ihrer
README.md
Datei. Dies ist normalerweise zwischen<section>
oder<article>
Tags. Ersetzen Sie diesen HTML-{{ content }}
Code durch den Text, mit dem wir diese Datei als Jekyll verwenden können. Die Datei, auf die wir das Layout anwenden, wird dort platziert, wo sich das Inhalts-Tag befindet.Suchen Sie das CSS für Ihr Projektseitenthema. Für mich war dies eine Zeile wie die folgende:
<link rel='stylesheet' href='stylesheets/stylesheet.css' />
Dies muss geändert werden in
<link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />
{{ site.path }}
.Auf diese Weise rendert Jekyll die Markdown-Datei als Inhalt des
index.html
Layouts im_layouts
Verzeichnis. Um diesen Prozess nicht nur für die Datei README.md, sondern auch für andere Dokumente in Ihrem Hauptzweig zu automatisieren, habe ich die folgenden Schritte ausgeführt:Erstellt die aufgerufene Datei
post-commit
mit den folgenden Angaben :BEARBEITEN: Ich habe das obige Skript sowohl für die
README.md
Datei als auch für den Abschlag aktualisiertdocs/*
, damit beide dieselbe Layoutdatei verwenden. Dies ist ein viel besseres Setup als das, was ich vorher hatte. Dieses Skript befindet sich in Ihrem.git/hooks/
Verzeichnis. Bash muss auf deinem Weg sein.Erstellen Sie die Datei wie
_config.yml
folgtDas obige Skript synchronisiert auch Markdown-Dateien, die sich im
docs/*
Verzeichnis desmaster
Zweigs befinden, damit sie auch auf der GitHub Pages-Site angezeigt werden können. Die relative Verknüpfung mit diesen Dokumenten funktioniert, wenn Sie die folgende jQuery-Funktion einschließen, um die.md
Erweiterung von den Ankern auf demgh-pages
Zweig zu entfernen. Sie können das folgende Skriptindex.html
im_layouts
Verzeichnis hinzufügen :BEARBEITEN: Ich habe den obigen Code in meinem Repository geändert. Dies war eine schnelle und schmutzige Methode, aber es funktioniert nicht in allen Fällen richtig, wenn Sie wissen, was ich meine. Beispielsweise
company.mdata.md
würde die Markdown-Datei nicht verarbeitet korrekt. Um dies zu beheben, habe ich dies auf das folgende Skript aktualisiert, das die href genauer überprüft und die Erweiterung entfernt, wenn sie gefunden wird. Ich habe das Skript auch allgemeiner gestaltet, sodass andere Erweiterungen durch Ändern derext
Variablen entfernt werden können. Hier ist der Code:Ich habe ein Beispiel-Repo unter CoryG89 / docsync eingerichtet , das hier eine Projektseite enthält , wenn Sie sehen möchten , wie dies alles zusammenarbeitet.
quelle
Meine Lösung für das Problem der Synchronisierung einer README-Datei mit einer Github-Seite weicht geringfügig von der oben genannten ab. Anstatt eine separate JavaScript-Markdown-Engine zu verwenden, kann die Github-API verwendet werden, um eine als HTML gerenderte Markdown-Datei zurückzugeben.
README.md
vonhttps://api.github.com/repos/<owner>/<repo>/contents/README.md
.window.atob( JSON.parse( blob ).content );
Das entschlüsselte Beitrag
README
zuhttps://api.github.com/markdown
in einem JSON KörperFügen Sie den gerenderten HTML-Code wie von Brad Rhodes in ein DOM-Element ein .
Zwei Vorbehalte zu diesem Ansatz:
Für eine Seite mit wenig Verkehr, auf der die Ladezeit nicht kritisch ist (~ 1-2 Sekunden), funktioniert die obige Methode gut genug.
quelle
Sie können DocumentUp verwenden , um Ihre README.md zu rendern.
quelle
Ich habe ein paar Ideen, wie Sie eine einzelne Readme-Datei zwischen Ihrer Dokumentationssite und dem Haupt-Github-Repo teilen können:
Sie können nur einen einzigen Gh-Seiten-Zweig verwenden, der sowohl Ihren Code als auch eine Jekyll-Dokumentationssite enthält. Ihr Repository könnte etwas überladen sein und Sie müssen einen YAML-Header oben in die Readme-Datei einfügen. Es unterstützt fast die relative Verknüpfung. Das Problem ist, dass wenn Sie möchten, dass Jekyll Ihren Markdown rendert, es eine .html-Erweiterung erhält. Vielleicht gibt es aber eine Möglichkeit, dies zu konfigurieren. Hier ist ein Beispiel, das ich zusammengeschmissen habe, um zu sehen, ob es funktioniert.
Sie können AJAX-Aufrufe auf Ihrer Dokumentationssite verwenden, um die Readme-Datei aus Ihrem Hauptzweig zu lesen und sie dann mit einem Javascript Markdown-Renderer zu rendern . Das Laden dauert etwas länger und unterstützt keine relativen Links, ohne dass Sie ein cleveres Javascript schreiben. Es ist auch mehr Arbeit zu implementieren als Idee 1.
quelle
Ein weiterer zu berücksichtigender Weg ist das Einrichten eines Pre-Commit-Hooks, der die relevanten Seiten erstellt. Ich mache das in einem meiner Repositories . Sie müssten wahrscheinlich den automatischen Seitengenerator über Bord werfen und einfach selbst in den
gh-pages
Zweig gehen und etwas Besonderes tun, um Ihre Dokumente in HTML oder eine Jekyll-Site umzuwandeln, wie Nathan vorschlägt .In diesem Repository drücke ich so , um
gh-pages
identisch zu bleibenmaster
. Es gibt auch viele andere Möglichkeiten , dies zu tun. Dies ist jedoch möglicherweise nicht ideal für Ihre Situation (Sie möchten möglicherweise nicht, dass sie identisch sind).Der Grund, warum ich für diese Frage ein Kopfgeld angeboten hatte, war, dass ich gehofft hatte, jemand hätte einen besseren Workflow. Diese Methode ist kompliziert und unflexibel und erfordert, dass jeder seine Hooks synchron hält.
quelle
Eine andere Methode, mit der ich ziemlich erfolgreich arbeiten konnte, ist die Verwendung von Ajax zum Abrufen der Dokumente mithilfe der Github-API und einer Javascript-Markdown-Engine zum Rendern des HTML-Codes (wie auch von Nathan vorgeschlagen).
Nathan äußerte sich besorgt über die Leistung, aber meiner Erfahrung nach wird sie scheinbar sofort geladen, sodass ich nicht denke, dass dies tatsächlich ein Problem ist.
Der Vorteil ist, dass es einfach einzurichten ist und Ihre Dokumente immer aktualisiert werden, selbst wenn Sie den Markdown nur direkt in einem Browser auf github bearbeiten.
Ich habe ein Beispiel auf Github-Seiten unter http://bradrhodes.github.io/GithubDocSync/ eingerichtet, um zu zeigen, dass es funktioniert.
quelle
Eine andere Möglichkeit für die von Nathan und Brand Rhodes beschriebene Methode ist die Verwendung eines großartigen Tools: FlatDoc, erstellt von Rico Sta. Cruz.
FlatDoc lädt die Dokumentation (README.md oder eine andere Markdown-Datei) per Ajax, analysiert sie und zeigt sie mit allen Extras und sogar einem Seitenleistenmenü für die Navigation an!
Es hat in seiner API eine Hilfsmethode zum Laden von Dateien vom GitHub-Repo-Master erstellt (kann aber auch überall im Web geladen werden).
Anleitung
Beginnen Sie mit dem Kopieren der folgenden HTML-Vorlage in Ihre index.html in Ihrem gh-pages-Zweig. Weitermachen mit:
in der Datei. Probieren Sie es lokal in Ihrem Browser aus. Übernehmen Sie dann die Änderungen und übertragen Sie sie. Jetzt wird Ihre Github-Seite immer mit Ihrer README.md-Datei in Ihrem Hauptzweig aktualisiert.
Wenn das Standarddesign für Sie nicht zufriedenstellend ist, können Sie es mit Ihrem eigenen CSS neu gestalten.
quelle
Ich möchte auch Dokumente in Master bearbeiten und in Gh-Seiten veröffentlichen. Ich möchte die Dokumente mit dem Quellcode auf dem neuesten Stand halten, und das scheint der beste Weg zu sein. Für mich ist dies in Arbeit, aber ich habe Corys Skript als Ausgangspunkt genommen und es ein wenig erweitert, damit es
_layouts
sofort funktioniert, solange es einen Gh-Pages-Zweig mit (dh einer Jekyll-Site) gibt. Es konvertiert Fencing im Backtick-Stil (für Codeblöcke), die beim Durchsuchen von Github-Quellen gut funktionieren, jedoch nicht bei Gh-Seiten. Ich verwende einindex.md
mit einem Include für das Projekt,README.md
damit ich einen Header und einige andere Dekorationen hinzufügen kann. Diese Version behandelt auch die Dokumentation in verschachtelten Verzeichnissen namens "docs", die ich in einem Projekt mit mehreren Modulen nützlich finde (keine Git-Submodule, nur Unterverzeichnisse):.git/hooks/post-commit
Eine weitere Abweichung vom Original besteht darin, dass
page.home
auf allen Seiten eine Variable festgelegt wird . Dies kann verwendet werden, um den relativen Pfad des Stammverzeichnisses zu lokalisieren, sodass statische Ressourcen wie CSS gefunden werden können. In habe_layouts/.default.html
ich:Auf diese Weise kann ich das CSS bearbeiten, die Jekyll-Site lokal erstellen und das Ergebnis in einem Browser anzeigen, ohne darauf warten zu müssen, dass Github es auf dem Server erstellt.
quelle
Ich habe kürzlich ein Paket gh-pages-generator erstellt , um dieses Problem zu lösen. Es generiert eine mehrseitige Site mit mehreren MD-Dateien und einer Konfigurationsdatei.
Alle Links zwischen den Seiten werden korrekt aktualisiert. Es ist relativ einfach, es zu einem Teil von CI zu machen, Änderungen wieder in den gh-pages-Zweig zu übernehmen.
Ich benutze es hier und hier .
quelle
Es ist nicht schwer , zwei Kopien und Pasten in das Terminal und Sie sind fertig.
Jekyll
Mit dieser Option können Sie Ihre Markdown-Datei importieren und anschließend in HTML konvertieren. Der Trick besteht darin, Ihre mitREADME.md
in Ihreindex.md
Datei zu importieren{% include_relative README.md %}
. So können wir das machen:Es lohnt sich herauszufinden, wie man eine Super-Barebone-
Jekyll
Site auf Github einrichtet (es sind nur zwei Dateien! )Die Einrichtung
Sie können die beiden Dateien kopieren und Ihre Seite mit Ihrer aktuellen Readme-Datei versehen, indem Sie nur dieses einmalige Setup ausführen ( kopieren Sie den gesamten Codeblock und fügen Sie ihn in das Terminal ein ):
Automatisieren
Dann müssen wir nur noch die Aufgabe automatisieren, alle Änderungen vor jedem Push von
master
in dengh-pages
Zweig zu kopieren . Wir können dies tun, indem wir dieses Skript ausführen ( Sie können es kopieren und in das Terminal einfügen ).Es wird ein Push-Hook erstellt, der alle Änderungen aus dem
master
Zweig beigh-pages
jeder Ausführung kopiertgit push
.Das ist es. Erledigt.
quelle