Erstellen einer lokalen Umgebung

Du kannst die Anwendung GitHub Docs lokal auf deinem Computer ausführen.

In diesem Artikel

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 vonJekyll unterstützt wird. Einige Jahre danach wurde sie zuNanoc 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 imcontent-Verzeichnis befinden.
  • Dateien imdata-Verzeichnis stehen Vorlagen über das {% data %}-Tag zur Verfügung.
  • Markdowndateien könnenFrontmatter enthalten.
  • Das Jekyll-Plug-In-Verhaltenredirect_from wird 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 diepackage.json-Datei im Repository GitHub Docs an. Die Node-Version ist in demengine-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 dunodenv verwendest, findest du Anweisungen zum Wechseln der Node.js-Versionen in dernodenv-Dokumentation.

Starten eines lokalen GitHub Docs-Servers

Sobald du Node.js installiert hast (einschließlich des beliebtennpm-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 Umgebung zuzugreifen, rufelocalhost:4000 in deinem Browser auf.

Wenn du den lokalen Server beenden möchtest, drücke in deinem TerminalfensterSTRG+C.

Hinweis

In der Regel musst dunpm ci undnpm run build nur immer dann ausführen, wenn du die neueste Version eines Branchs pullst.

  • npm ci führt eine saubere Installation von Abhängigkeiten aus, ohne diepackage-lock.json-Datei zu aktualisieren.
  • npm run build erstellt statische Ressourcen wie JavaScript- und CSS-Dateien.

Weitere Informationen zum Debuggen und zur Problembehandlung der GitHub Docs-Anwendung findest du unterProblembehandlung für Ihre Umgebung im github/docs-Repository.

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 dasstart-Skript inpackage.json vorübergehend in bearbeiten und dieENABLED_LANGUAGES-Variable aktualisieren.

Wenn du beispielsweise zusätzlich zu Englisch Japanisch und Portugiesisch aktivieren möchtest, kannst dupackage.json bearbeiten undENABLED_LANGUAGES='en,ja,pt' imstart-Skript festlegen. Starte dann den Server neu, damit die Änderung wirksam wird.

Hinweis

Bevor du deine Änderungen committest, solltest du die Dateipackage.json in den ursprünglichen Zustand zurückversetzen.

Die unterstützten Sprachcodes sind insrc/languages/lib/languages.ts 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 unterArbeiten an GitHub-Dokumentationen in einem Codespace.

Weiterführende Themen