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:
/docs/*.md
irgendwie mit meinen Github-Seiten synchronisieren und sie irgendwie rendern und/oder thematisieren? 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.
git checkout gh-pages
mkdir _layouts
mv index.html _layouts
git checkout master -- README.md
mv README.md index.md
index.md
den folgenden Text vor. ---
layout: index
---
Sie müssen auch die Datei index.html
öffnen und folgende Änderungen vornehmen:
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.
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' />
{{ 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.
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.
README.md
von https://api.github.com/repos/<owner>/<repo>/contents/README.md
ab.window.atob( JSON.parse( blob ).content );
Veröffentlichen Sie die dekodierte README
in https://api.github.com/markdown
in einem JSON-Body
{
"text": "<README>",
"mode": "markdown",
"context": "<owner>/<repo>"
}
Fügen Sie den gerenderten HTML-Code in ein DOM-Element ein, wie von Brad Rhodes ausgeführt.
Zwei Vorbehalte gegen diesen Ansatz:
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:
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.
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:
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).
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! )
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
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.