Erstellen einer lokalen Umgebung

Sie können die GitHub Docs Anwendung lokal auf Ihrem 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 von Jekyll unterstützt wird. Einige Jahre danach wurde sie zu Nanoc migriert, einem anderen Ruby-Generator für statische Websites.

Heute ist es ein dynamischer Node.js Webserver, der von Express unterstützt wird und Middleware verwendet, um ordnungsgemäße HTTP-Umleitungen, Sprachheadererkennung und dynamische Inhaltsgenerierung zu unterstützen, um die verschiedenen Varianten der GitHubProduktdokumentation zu unterstützen, z. B. Free, Pro, & Team und GitHub Enterprise Server.

Die Tools für diese Website haben sich im Laufe der Jahre geändert, aber viele der bewährten Autorenkonventionen der ursprünglichen Jekyll-Website wurden bewahrt.

  • Inhalte werden in Markdown-Dateien geschrieben. Diese befinden sich im content Verzeichnis.
  • Der Inhalt kann die Sprache "Liquid templating" verwenden. Siehe Verwenden von Markdown und Liquid in GitHub Docs.
  • Dateien im Verzeichnis data sind für Vorlagen über den {% data %}-Tag verfügbar.
  • Markdowndateien können Frontmatter enthalten.
  • Das Jekyll-Plug-In-Verhalten redirect_from wird unterstützt.

Einrichten deiner lokalen Entwicklungsumgebung

Sie können das GitHub Docs Repository klonen und die Anwendung lokal auf Ihrem Computer ausführen, nachdem sie anfänglich eingerichtet wurde.

Installieren von Node.js

Die GitHub Docs Website wird von Node.jsunterstützt. Sie wird in macOS-, Windows- und Linux-Umgebungen ausgeführt.

Zum Ausführen der Website benötigst du Node.js. Um Node.jszu installieren, laden Sie das Installationsprogramm "LTS" von nodejs.org herunter. Um zu überprüfen, welche Node-Version Sie benötigen, können Sie die package.json Datei im GitHub Docs Repository anzeigen. 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 Umgebung zuzugreifen, rufe localhost:4000 in deinem Browser auf.

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

Hinweis

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 ci führt eine saubere Installation von Abhängigkeiten aus, ohne die package-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 finden Sie unter Fehlerbehebung in Ihrer 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 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.

Hinweis

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.ts definiert.

Verwenden von GitHub Codespaces

Als Alternative zur lokalen Ausführung GitHub Docs können Sie verwenden GitHub Codespaces. GitHub Codespaces Sie können Ihre Änderungen direkt über Ihren Browser bearbeiten, in der Vorschau anzeigen und testen.

Weitere Informationen zur Verwendung eines Codespaces zum Bearbeiten von GitHub Dokumentation finden Sie unter Arbeiten an GitHub-Dokumentationen in einem Codespace.

Weiterführende Lektüre