web-dev-qa-db-de.com

Wie kann ich Dokumentation mit Github Pages synchronisieren?

Ich habe ein Projekt zusammen mit mehreren Leuten 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 Unterdomäne unserer GitHub-Organisation gehostet wird, und haben den Automatic Page Generator verwendet, der einfach in unsere README.md -Datei geladen wurde, als wir unsere Seite erstellt haben Aktualisieren Sie unsere README.md-Datei, die Projektseite wird nicht aktualisiert. Wechseln Sie stattdessen zur Registerkarte GitHub-Einstellungen und erstellen Sie die Projektseite neu. Laden Sie die README.md-Datei erneut, wenn Sie dies tun.

Nachdem ich über relative Verknüpfung gelesen habe, arbeite ich zwischen Dokumentationsdateien auf den GitHub-Projektverzeichnisseiten. Ich mag den Markdown sehr, da er Tonnen von Zeit spart, da wir den gesamten HTML-Code für unser Projekt von Hand schreiben müssen Ich möchte jedoch eine README.md-Datei haben, die relative Links zu anderen Dokumentationsdateien enthält, die sich unter docs/*.md befinden. Ich hatte gehofft, dass es eine einfache Lösung gibt, damit meine anderen Dokumentationsdateien auch in die Datei aufgenommen werden können my gh-pages branch und werde unter meiner GitHub Pages Subdomain gehostet und gerendert und/oder thematisiert.

Mit anderen Worten, meine Fragen sind:

  • Gibt es eine Möglichkeit, meine README.md-Datei auf meiner Github Page-Unterdomäne automatisch zu aktualisieren?
    • [BEARBEITEN]: Nein scheint die Antwort zu sein, wenn der automatische Seitengenerator verwendet wird. Sie müssen zur Einstellungsseite für das Repo gehen und es bei jeder Änderung neu laden, um es zu aktualisieren.
  • Gibt es eine Möglichkeit, wie meine relativen Links zu meiner Dokumentation in meiner README.md-Datei auf meinen Github-Seiten funktionieren, vielleicht kann ich meinen /docs/*.md irgendwie mit meinen Github-Seiten synchronisieren und sie irgendwie rendern und/oder thematisieren?
  • Besser noch, gibt es eine noch einfachere Möglichkeit, dies zu tun und vielleicht nur eine Kopie meiner README.md und der Dokumentation zu haben, die sowohl auf gh-pages als auch in meinem Hauptzweig verwendet wird und alles am einfachsten macht?
    • [EDIT]: Es scheint, dass dies fast definitiv ein Nein ist. Ich dachte über die Möglichkeit nach, etwas in GitHub zu integrieren, um dies zu ermöglichen. Es scheint, dass GitHub Pages in Zukunft eine bessere Unterstützung für diese Art von Dingen bieten könnte, oder ich hoffe es zumindest auf jeden Fall.
79
Cory Gross

Ich werde eine Lösung posten, die ich eingerichtet habe, um die Tatsache zu nutzen, dass GitHub Pages Jekyll verwendet, der bereits den Automatic Page Generator verwendet.

  1. git checkout gh-pages
  2. mkdir _layouts
  3. mv index.html _layouts
  4. git checkout master -- README.md
  5. mv README.md index.md
  6. Fügen Sie index.md den folgenden Text vor. 

---
layout: index
---

Sie müssen auch die Datei index.html öffnen und folgende Änderungen vornehmen:

  1. Entfernen Sie das gerenderte HTML aus dem Markdown in Ihrer README.md-Datei. Dies ist normalerweise zwischen <section>- und <article>-Tags. Ersetzen Sie diesen HTML-Code durch den Text {{ content }}. Dadurch können Sie diese Datei als Jekyll verwenden. Die Datei, auf die wir das Layout anwenden, wird dort platziert, wo sich das Content-Tag befindet.

  2. Suchen Sie das CSS für das Thema Ihrer Projektseite. für mich war dies eine Zeile wie die folgende:

    <link rel='stylesheet' href='stylesheets/stylesheet.css' />

    Dies muss in geändert werden

    <link rel='stylesheet' href='{{ site.path }}/stylesheets/stylesheet.css' />

  3. Allen anderen auf Ihrer Website gespeicherten Assets, die in diesem Layout verwendet werden, muss {{ site.path }} vorangestellt werden.

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 zu automatisieren, sondern auch für andere Dokumente, die Sie möglicherweise in Ihrem Master-Zweig haben, habe ich folgende Schritte unternommen:

Erstellt die Datei mit dem Namen post-commit, die Folgendes enthält:

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # Layout prefix is prepended to each markdown file synced
    ###################################################################
    LAYOUT_PREFIX='---\r\nlayout: index\r\n---\r\n\r\n'

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    echo -e $LAYOUT_PREFIX > index.md
    cat README.md >> index.md
    rm README.md
    git add index.md
    git commit -a -m "Sync README.md in master branch to index.md in gh-pages"

    # Sync the markdown files in the docs/* directory
    ###################################################################
    git checkout master -- docs
    FILES=docs/*
    for file in $FILES
    do
        echo -e $LAYOUT_PREFIX | cat - "$file" > temp && mv temp "$file"
    done

    git add docs
    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following Push if you want to auto Push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git Push Origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

EDIT: Ich habe das obige Skript für die README.md-Datei und das Markdown in docs/* aktualisiert, damit beide dieselbe Layoutdatei verwenden. Dies ist ein viel besseres Setup als zuvor. Dieses Skript wird in Ihr .git/hooks/-Verzeichnis geschrieben. Bash muss auf Ihrem Weg sein.

Erstellen Sie die Datei _config.yml mit den folgenden Angaben

markdown: redcarpet
path: http://username.github.io/reponame

Das obige Skript synchronisiert auch Markdown-Dateien, die sich im Verzeichnis docs/* des Zweigs master befinden, damit sie auch auf der GitHub Pages-Site angezeigt werden können. Die relative Verknüpfung zu diesen Dokumenten funktioniert, wenn Sie die folgende jQuery-Funktion verwenden, um die Erweiterung .md von den Ankern im Zweig gh-pages zu entfernen. Sie können das folgende Skript zu index.html im Verzeichnis _layouts hinzufügen:

$(document).on('ready', function () {
    $('a').each(function (i, e) {
        var href = e.href;
        if (href.search('.md') > 0)
            $(this).attr('href', href.split('.md')[0]);
    });
});

EDIT: Ich habe den Code oben in meinem Repository geändert. Dies war ein schneller und schmutziger Weg, dies zu tun, funktioniert aber nicht in jedem Fall, wenn Sie wissen, was ich meine. Zum Beispiel die Markdown-Datei company.mdata.md würde nicht korrekt verarbeitet. Um dies zu beheben, habe ich das folgende Skript aktualisiert, das href genauer prüft und die Erweiterung entfernt, wenn sie gefunden wird. Ich habe das Skript außerdem generischer gestaltet, sodass andere Erweiterungen entfernt werden können, indem die Variable ext geändert wird. Hier ist der Code:

$(function () {
    $('a').each(function () {
        var ext = '.md';
        var href = $(this).attr('href');
        var position = href.length - ext.length;
        if (href.substring(position) === ext)
            $(this).attr('href', href.substring(0, position));
    });
});

Ich habe ein Beispiel-Repo unter CoryG89/docsync eingerichtet, das hier eine [ -Projektseite] hat.

36
Cory Gross

Meine Lösung für das Problem des Synchronisierens eines README mit einer Github-Seite weicht etwas von dem oben genannten ab. Anstelle eines separaten JavaScript-Markdown-Moduls können Sie die Github-API verwenden, um eine als HTML gerenderte Markdown-Datei zurückzugeben. 

  1. Rufen Sie den README.md von https://api.github.com/repos/<owner>/<repo>/contents/README.md ab.
  2. Decodieren Sie die Base64-Antwort: window.atob( JSON.parse( blob ).content );
  3. Veröffentlichen Sie die dekodierte README in https://api.github.com/markdown in einem JSON-Body

     {
       "text": "<README>",
       "mode": "markdown",
       "context": "<owner>/<repo>"
     }
    
  4. Fügen Sie den gerenderten HTML-Code in ein DOM-Element ein, wie von Brad Rhodes ausgeführt.

Zwei Vorbehalte gegen diesen Ansatz:

  1. Das Durchführen von zwei seriellen Anforderungen verlangsamt das Laden der Seite.
  2. Beim Zugriff auf die Github-API können Ratenbeschränkungen auftreten.

Für eine Seite mit wenig Verkehr, bei der die Ladezeit nicht kritisch ist (~ 1-2 Sekunden), funktioniert die obige Methode gut genug.

5
kgryte

Sie können DocumentUp verwenden, um Ihre README.md zu rendern.

4
niutech

Ich habe ein paar Ideen für die gemeinsame Nutzung einer einzelnen Readme-Datei zwischen Ihrer Dokumentationssite und dem Haupt-Github-Repository:

  1. Sie können nur eine einzige gh-pages-Verzweigung verwenden, die 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 der 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, er eine .html-Erweiterung erhält. Möglicherweise gibt es jedoch eine Möglichkeit, dies zu konfigurieren. Hier ist ein Beispiel, das ich zusammengestellt habe, um zu prüfen, ob es funktioniert.

  2. Sie können AJAX Aufrufe in 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 es werden keine relativen Links unterstützt, ohne dass Sie ein geschicktes Javascript schreiben. Es ist auch mehr Arbeit zu implementieren als Idee 1.

3
Nathan Breit

Ein weiterer zu berücksichtigender Weg ist das Einrichten eines Pre-Commit Hook , der die relevanten Seiten erstellt. Ich mache das in eines meiner Repositories . Wahrscheinlich müssten Sie den automatischen Seitengenerator aufgeben und einfach zum gh-pages-Zweig wechseln. Außerdem müssen Sie etwas Besonderes tun, um Ihre Dokumente in HTML oder eine Jekyll-Site als Nathan schlägt umzuwandeln.

In diesem Repository so drücke ich , um gh-pages mit master identisch zu bleiben. Es gibt eine Menge andere Möglichkeiten , um dies auch zu tun. Dies ist jedoch möglicherweise nicht ideal für Ihre Situation (Sie möchten möglicherweise, dass sie nicht identisch sind).

Der Grund, warum ich zu dieser Frage Kopfgeld hatte, war jedenfalls, weil ich hoffte, dass jemand einen besseren Workflow hatte. Diese Methode ist irgendwie kompliziert und unflexibel und erfordert, dass alle ihre Haken synchron halten.

3
Matt Kantor

Eine andere Möglichkeit für die von Nathan und Brand Rhodes beschriebene Methode ist die Verwendung eines großartigen Tools: FlatDoc von Rico Sta. Cruz.

FlatDoc lädt mit ajax die Dokumentation (README.md oder eine andere Markdown-Datei), analysiert sie und zeigt sie mit allen Extras und sogar einem Seitenleistenmenü zur Navigation an!

Es hat in seiner API eine Hilfsmethode zum Laden von Dateien vom GitHub-Repo-Master (kann aber auch an anderer Stelle aus dem Web geladen werden).

Anweisungen

Beginnen Sie mit dem Kopieren der folgenden html-Vorlage in Ihre index.html in Ihrem gh-pages-Zweig. Weitermachen mit:

  • Ersetzen Sie "USER" durch Ihren GitHub-Benutzernamen
  • Ersetzen Sie "REPO" durch Ihren GitHub-Repo-Namen
  • Ersetzen Sie "Ihr Projekt" durch Ihren Projektnamen

in der Datei. Probieren Sie es lokal in Ihrem Browser aus. Dann begehen Sie und drücken Sie die Änderungen. Jetzt wird Ihre Github-Seite immer mit Ihrer README.md-Datei in Ihrem Master-Zweig aktualisiert.

Wenn das Standarddesign für Sie nicht zufriedenstellend ist, können Sie es mit Ihrer eigenen CSS anpassen.

2
Khalid Salomão

Eine weitere Methode, die ich ziemlich erfolgreich zum Laufen gebracht habe, 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).

  1. Verwenden Sie die Github-API und JSONP, um das Dokument von Github abzurufen
  2. Decodieren Sie den base64-Inhalt in der Antwort von der Github-API
  3. Rendern Sie die Markierung mit einem JavaScript-Markdown-Modul
  4. Zeigen Sie das gerenderte HTML an

Nathan äußerte sich besorgt über die Leistung, aber meiner Erfahrung nach lädt es sich augenblicklich auf, daher glaube ich nicht, dass es tatsächlich ein Problem ist.

Der Vorteil ist, dass das Setup einfach ist und Ihre Dokumente immer aktualisiert werden, selbst wenn Sie den Markdown 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.

2
Brad Rhodes

Ich möchte auch Dokumente in master bearbeiten und in gh-pages veröffentlichen - ich halte die Dokumente gerne mit dem Quellcode auf dem neuesten Stand und das scheint der beste Weg zu sein. Dies ist in Arbeit für mich, aber ich habe Corys Skript als Ausgangspunkt genommen und etwas erweitert, damit es sofort funktionieren kann, solange es einen gh-pages-Zweig mit _layouts (dh einem Jekyll) gibt Seite? ˅). Es konvertiert Backtick-Style-Fencing (für Codeblöcke), das beim Github-Source-Browsing gut funktioniert, nicht jedoch bei den Gh-Pages. Ich benutze einen index.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 mit dem Namen "docs", die ich in einem Projekt mit mehreren Modulen (nicht git-Untermodule, nur Unterverzeichnisse) nützlich finde:

.git/hooks/post-commit

#!/bin/bash
###
### The following block runs after commit to "master" branch
###
if [ `git rev-parse --abbrev-ref HEAD` == "master" ]; then

    # function to convert a plain .md file to one that renders nicely in gh-pages
    function convert {
        # sed - convert links with *.md to *.html (assumed relative links in local pages)
        # awk - convert backtick fencing to highlights (script from bottom of file)
        sed -e 's/(\(.*\)\.md)/(\1.html)/g' "$1" | awk -f <(sed -e '0,/^#!.*awk/d' $0) > _temp && mv _temp "$1"
    } 

    if ! git show-ref --verify --quiet refs/heads/gh-pages; then
        echo "No gh-pages, so not syncing"
        exit 0
    fi

    # Switch to gh-pages branch to sync it with master
    ###################################################################
    git checkout gh-pages

    mkdir -p _includes

    # Sync the README.md in master to index.md adding jekyll header
    ###################################################################
    git checkout master -- README.md
    if [ -f README.md ]; then
        cp README.md _includes/
        convert _includes/README.md
        git add README.md
        git add _includes/README.md
    fi

    # Generate index if there isn't one already
    ###################################################################
    if [ ! -f index.md ]; then
        echo -e '---\ntitle: Docs\nlayout: default\n---\n\n{% include README.md %}' > index.md
        git add index.md
    fi

    # Generate a header if there isn't one already
    ###################################################################
    if [ ! -f _includes/header.txt ]; then
        echo -e '---\ntitle: Docs\nlayout: default\nhome: \n---\n\n' > _includes/header.txt
        git add _includes/header.txt
    fi

    # Sync the markdown files in all docs/* directories
    ###################################################################
    for file in `git ls-tree -r --name-only master | grep 'docs/.*\.md'`
    do
        git checkout master -- "$file"
        dir=`echo ${file%/*} | sed -e "s,[^/]*,..,g"`
        cat _includes/header.txt | sed -e "s,^home: .*$,home: ${dir}/," > _temp
        cat "$file" >> _temp && mv _temp "$file"
        convert "$file"
        git add "$file"
    done

    git commit -a -m "Sync docs from master branch to docs gh-pages directory"

    # Uncomment the following Push if you want to auto Push to
    # the gh-pages branch whenever you commit to master locally.
    # This is a little extreme. Use with care!
    ###################################################################
    # git Push Origin gh-pages

    # Finally, switch back to the master branch and exit block
    git checkout master
fi

exit $?

#!/usr/bin/awk
{
   # Replace backtick fencing (renders well when browsing github) with jekyll directives
   if (/```/) {
      IN = IN?0:1 # Are we already in a fenced section? Toggle.
      if (IN) { # If we are starting a fenced section
         if (/```\s*$/) {
           $0 = $0"text" # empty language is OK for backticks but not for jekyll
         }
         gsub(/```/, "{% highlight ")
         print $0" %}"
      } else { # ending a fenced section
        print "{% endhighlight %}" 
      }
    } else { # not a fencing line
      if (IN) { # but in a fenced section, so add indent to make sure code is rendered with <pre>
        print "    "$0
      } else {
        print
      }
    }
}

Eine weitere Variation gegenüber dem Original besteht darin, dass auf allen Seiten eine Variable page.home festgelegt wird. Hiermit kann der relative Pfad des Root-Verzeichnisses ermittelt werden, sodass statische Ressourcen wie css gesucht werden können. In _layouts/.default.html habe ich:

<link rel="stylesheet" href="{{ page.home }}css/main.css">

Auf diese Weise kann ich die CSS bearbeiten, die Jekyll-Site lokal erstellen und das Ergebnis in einem Browser anzeigen, ohne auf Github warten zu müssen, um es auf dem Server zu erstellen.

1
Dave Syer

Es ist nicht schwer , zwei Kopieren und Einfügen in das Terminal und Sie sind fertig.

Mit Jekyll können Sie Ihre Markdown-Datei importieren und diese anschließend in HTML konvertieren. Der Trick besteht darin, Ihren README.md Mit index.md In Ihre {% include_relative README.md %} - Datei zu importieren. So können wir das machen:

Es lohnt sich, einen Blick auf wie man eine Super Barebones Jekyll Seite auf Github erstellt (es sind nur zwei Dateien! )

Die Einrichtung

Sie können die beiden Dateien kopieren und Ihre Seite mit Ihrer aktuellen Readme-Datei verwenden, indem Sie dieses einmalige Setup ausführen ( Kopieren des gesamten Codeblocks und in das Terminal einsteigen):

# Copy our two files to the gh-pages branch
git checkout -b gh-pages &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/_config.yml &&
wget https://raw.githubusercontent.com/lazamar/barebones-jekyll-project-readme/master/index.md &&
#
# Commit and publish our page on github
git add -A && git commit -m "Create project github page" &&
git Push --set-upstream Origin gh-pages |
#
git checkout master # go back to master branch

Automatisieren

Dann müssen wir nur noch die Aufgabe automatisieren, alle Änderungen von master vor jedem Push in den Zweig gh-pages Zu kopieren. Wir können das tun, indem wir dieses Skript ausführen ( Sie können es kopieren und in das Terminal einfügen)

$(cat > .git/hooks/pre-Push << EOF
#!/bin/sh
we_are_in_gh_pages="\$(git branch | grep -G "* gh-pages")"

if [ ! "\$we_are_in_gh_pages" ];
  then
    git checkout gh-pages &&
    git rebase master &&
    git Push -f &&
    git checkout master # go back to master branch
fi
EOF
) && chmod 775 .git/hooks/pre-Push

Es wird ein Push-Hook erstellt, der bei jeder Ausführung von gh-pages Alle Änderungen aus dem Zweig master nach git Push Kopiert.

Das war's. Fertig.

0

Ich habe vor kurzem 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 Bestandteil von CI zu machen, um Änderungen an den gh-pages-Zweig zurückzugeben.

Ich benutze es hier und hier .

0
esp