Wie kann ich Dokumentation mit Github Pages synchronisieren?

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.

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

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.

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.

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.

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.

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.

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.

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 .