Informationen zur GitHub Docs-Websitestruktur
Die GitHub Docs-Website war ursprünglich eine Ruby on Rails-Webanwendung. Einige Zeit später wurde sie in eine statische Website umgewandelt, die von Jekyll unterstützt wird. Einige Jahre danach wurde sie zu Nanoc migriert, einem anderen Ruby-Generator für statische Websites.
Heute handelt es sich um einen dynamischen Node.js-Webserver auf Basis von Express, der Middleware zur Unterstützung ordnungsgemäßer HTTP-Weiterleitungen, der Erkennung von Sprach-Headern und der Generierung dynamischer Inhalte zur Unterstützung der verschiedenen Varianten der Produktdokumentation von GitHub wie Free, Pro und Team sowie GitHub Enterprise Server verwendet.
Die Tools für diese Website haben sich im Laufe der Jahre geändert, aber viele der bewährten Konvention für die Dokumenterstellung der ursprünglichen Jekyll-Website sind erhalten geblieben.
- Der Inhalt wird in Markdowndateien geschrieben, die sich im
content-Verzeichnis befinden.
- Dateien im
data-Verzeichnis stehen Vorlagen über das{% data %}-Tag zur Verfügung. - Markdowndateien können Frontmatter enthalten.
- Das Jekyll-Plug-In-Verhalten
redirect_fromwird unterstützt.
Einrichten deiner Lokalen Entwicklungsumgebung
Du kannst das GitHub Docs-Repository klonen und die Anwendung nach einer anfänglichen Einrichtung lokal auf deinem Computer ausführen.
Installieren von Node.js
Die GitHub Docs-Website wird von Node.js unterstützt. Sie wird in macOS-, Windows- und Linux-Umgebungen ausgeführt.
Zum Ausführen der Website benötigst du Node.js. Um Node.js zu installieren, lade das Installationsprogramm „LTS“ von nodejs.org herunter. Um zu überprüfen, welche Node-Version du benötigst, sieh dir die package.json-Datei im Repository GitHub Docs an. Die Node-Version ist in dem engine-Feld aufgeführt, ähnlich wie im folgenden Beispiel, das angibt, dass du die Node-Hauptversion 16 oder die Node-Hauptversion 18 verwenden kannst.
"engines": {
"node": "^16 || ^18"
}
Wenn du nodenv verwendest, findest du Anweisungen zum Wechseln der Node.js-Versionen in der nodenv-Dokumentation.
Starten eines lokalen GitHub Docs-Servers
Sobald du Node.js installiert hast (einschließlich des beliebten npm-Paket-Managers), öffne dein Terminal, und führe die folgenden Befehle aus.
git clone https://github.com/github/docs
cd docs
npm ci
npm start
Du solltest nun über einen laufenden Server verfügen. Um auf deine lokale Vorschauumgebung zuzugreifen, besuche localhost:4000 in deinem Browser.
Wenn du den lokalen Server beenden möchtest, drücke in deinem Terminalfenster STRG+C.
Note
In der Regel musst du npm ci und npm run build nur immer dann ausführen, wenn du die neueste Version eines Branchs pullst.
npm ciführt eine saubere Installation von Abhängigkeiten aus, ohne diepackage-lock.json-Datei zu aktualisieren.npm run builderstellt statische Ressourcen wie JavaScript- und CSS-Dateien.
Weitere Informationen zum Debuggen und zur Problembehandlung der GitHub Docs-Anwendung findest du unter Problembehandlung für Ihre Umgebung im github/docs-Repository.
Verwenden von Browserverknüpfungen
Das src/bookmarklets-Verzeichnis im GitHub Docs-Repository enthält Browserverknüpfungen, die beim Durchsuchen der GitHub-Dokumentation helfen können. Weitere Informationen findest du im README des Verzeichnisses.
Aktivieren verschiedener Sprachen
Standardmäßig werden im lokalen ausgeführten Server nicht alle unterstützten Sprachen aktiviert. Wenn du einen lokalen Server mit einer bestimmten Sprache ausführen musst, kannst du das start-Skript in package.json vorübergehend in bearbeiten und die ENABLED_LANGUAGES-Variable aktualisieren.
Wenn du beispielsweise zusätzlich zu Englisch Japanisch und Portugiesisch aktivieren möchtest, kannst du package.json bearbeiten und ENABLED_LANGUAGES='en,ja,pt' im start-Skript festlegen. Starte dann den Server neu, damit die Änderung wirksam wird.
Note
Bevor du deine Änderungen committest, solltest du die Datei package.json in den ursprünglichen Zustand zurückversetzen.
Die unterstützten Sprachcodes sind in src/languages/lib/languages.js definiert.
Verwenden von GitHub Codespaces
Alternativ zum lokalen Ausführen von GitHub Docs kannst du GitHub Codespaces verwenden. Mit GitHub Codespaces kannst du deine Änderungen direkt in deinem Browser bearbeiten, in der Vorschau anzeigen und testen.
Weitere Informationen zum Verwenden eines Codespaces zum Arbeiten an der GitHub-Dokumentation findest du unter Arbeiten an GitHub-Dokumentationen in einem Codespace.