Installationsanleitungen für Ubuntu Ubuntu 26.04 LTS · x86_64 (amd64)

Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).

gh-pages

Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).

gh-pages ist ein kleines npm-Werkzeug, das einen fertig gebauten Ordner (z. B. dist) mit einem einzigen Befehl in den Branch gh-pages eines Git-Repositorys schiebt. GitHub Pages veröffentlicht diesen Branch dann als Webseite.

Vorbemerkungen

  • Kein apt-Paket: gh-pages gibt es nicht in den Ubuntu-Paketquellen. Es wird pro Projekt mit npm installiert. Aus den Ubuntu-Paketquellen kommen nur Git, Node.js und npm.
  • Version: Diese Anleitung verwendet gh-pages 6 (derzeit 6.3). Es läuft mit jeder Node.js-Version ab 10, das Node.js 22 aus Ubuntu 26.04 passt also.
  • Voraussetzung: Du hast ein Repository auf GitHub, und git push funktioniert von deinem Rechner aus (per SSH-Schlüssel oder Zugangstoken). gh-pages nutzt genau diesen Zugang.
  • Was gh-pages nicht tut: Es baut die Webseite nicht. Den Ordner mit den fertigen Dateien erzeugt vorher dein Werkzeug, z. B. VitePress, Docusaurus oder mdBook.

Installation

1. Paketlisten aktualisieren

Damit apt die aktuellen Versionen von Git, Node.js und npm kennt.

sudo apt update

2. Git, Node.js und npm installieren

Git überträgt die Dateien zu GitHub, Node.js führt gh-pages aus und npm lädt es herunter. Ist schon alles vorhanden, meldet apt das nur.

sudo apt install git nodejs npm

Prüfen: Beide Befehle geben eine Versionsnummer aus.

node --version

git --version

Beispielprojekt

Die folgenden Schritte zeigen gh-pages an einem kleinen Projekt. Hast du schon ein Projekt, beginne in dessen Ordner bei Schritt 6.

3. Repository von GitHub holen

Lädt ein bestehendes GitHub-Repository auf deinen Rechner. Ersetze BENUTZER und meine-seite durch deinen GitHub-Namen und den Namen des Repositorys. Das Repository sollte schon mindestens einen Commit haben (z. B. eine README.md, die GitHub beim Anlegen erzeugt).

git clone git@github.com:BENUTZER/meine-seite.git ~/meine-seite

4. In den Projektordner wechseln

Alle weiteren Befehle beziehen sich auf diesen Ordner.

cd ~/meine-seite

Prüfen: Unter origin steht die Adresse deines GitHub-Repositorys. An diese Adresse schickt gh-pages später die Dateien.

git remote -v

5. package.json anlegen

npm braucht die Datei package.json, um festzuhalten, welche Pakete das Projekt verwendet. -y übernimmt alle Vorschläge, ohne nachzufragen.

npm init -y

6. gh-pages installieren

Lädt gh-pages in den Ordner node_modules und trägt es in package.json ein. -D kennzeichnet es als Entwicklungswerkzeug, das nicht zur Webseite selbst gehört.

npm add -D gh-pages

Prüfen: Die Ausgabe zeigt die installierte Version, z. B. gh-pages@6.3.0.

npm ls gh-pages

7. node_modules von Git ausschließen

Der Ordner node_modules lässt sich jederzeit mit npm install wiederherstellen und gehört nicht ins Repository. gh-pages legt dort außerdem seinen Zwischenspeicher ab.

nano .gitignore

Füge diese Zeile ein (im Terminal mit Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:

node_modules

8. Ordner für die fertige Webseite anlegen

In einem echten Projekt erzeugt dein Werkzeug diesen Ordner beim Bauen. Für das Beispiel legst du ihn selbst an.

mkdir dist

9. Eine Testseite anlegen

Eine einfache HTML-Seite, an der du erkennst, ob die Veröffentlichung geklappt hat.

nano dist/index.html

Füge diesen Inhalt ein (im Terminal mit Strg+Umschalt+V), speichere mit Strg+O und Enter und beende nano mit Strg+X:

<!DOCTYPE html>
<html lang="de">
<head>
  <meta charset="utf-8">
  <title>Meine Seite</title>
</head>
<body>
  <h1>Hallo von GitHub Pages</h1>
</body>
</html>

10. Kurzbefehl in package.json eintragen

Ein Eintrag unter scripts erspart dir, die Optionen jedes Mal abzutippen. Danach genügt npm run deploy.

nano package.json

Suche mit Strg+W nach "test" und bestätige mit Enter. Lösche diese Zeile mit Strg+K und füge an ihrer Stelle diese Zeile ein. Speichere mit Strg+O und Enter und beende nano mit Strg+X:

    "deploy": "gh-pages -d dist --nojekyll"

Die Optionen bedeuten:

  • -d dist – dieser Ordner wird veröffentlicht
  • --nojekyll – legt eine leere Datei .nojekyll an. Sonst bereitet GitHub die Seite mit Jekyll auf und lässt dabei Ordner weg, die mit _ beginnen (das betrifft z. B. VitePress und Sphinx).

Der Abschnitt scripts sieht danach so aus:

  "scripts": {
    "deploy": "gh-pages -d dist --nojekyll"
  },

11. Projektdateien committen

Sichert package.json, package-lock.json und .gitignore im Branch main. Der Ordner dist wird hier mit übernommen, das ist für das Beispiel in Ordnung.

git add .

git commit -m "gh-pages einrichten"

git push

12. Webseite veröffentlichen

gh-pages kopiert den Inhalt von dist in den Branch gh-pages, erstellt dort einen Commit und schiebt ihn zu GitHub. Den Branch legt es beim ersten Mal selbst an.

npm run deploy

Prüfen: Die Ausgabe endet mit Published. Auf GitHub gibt es jetzt den Branch gh-pages mit den Dateien index.html und .nojekyll.

git ls-remote origin gh-pages

13. GitHub Pages einschalten

Einmalig im Browser: GitHub muss wissen, aus welchem Branch es die Webseite liefern soll.

  1. Öffne dein Repository auf GitHub.
  2. Klicke auf Settings und links auf Pages.
  3. Wähle unter Source den Eintrag Deploy from a branch.
  4. Wähle unter Branch den Eintrag gh-pages und den Ordner / (root) und klicke auf Save.

Prüfen: Nach ein bis zwei Minuten zeigt https://BENUTZER.github.io/meine-seite/ die Überschrift „Hallo von GitHub Pages“.

Mit anderen Werkzeugen verwenden

Bei einem echten Projekt ersetzt du in Schritt 10 nur dist durch den Ordner, in den dein Werkzeug baut, und baust vor npm run deploy die Seite neu:

WerkzeugOrdner für -d
mdBookbook
VitePress.vitepress/dist
Docusaurusbuild
Astro Starlightdist

Weil die Seite unter /meine-seite/ liegt und nicht direkt unter der Domain, muss dein Werkzeug das wissen. In VitePress trägst du dazu z. B. base: '/meine-seite/' in .vitepress/config.mts ein, in Docusaurus baseUrl. Ohne diese Angabe fehlen auf der veröffentlichten Seite Stile und Bilder.

Beispiel: mdBook unter eigener Domain veröffentlichen

So wird dieses Buch veröffentlicht: mdBook baut die Seiten in den Ordner book, gh-pages schiebt sie in den Branch gh-pages, und GitHub liefert sie unter der Subdomain installieren.wissen-ahrensburg.de aus. Die Schritte setzen voraus, dass gh-pages wie oben im Projekt installiert ist und origin auf das GitHub-Repository zeigt.

1. Kurzbefehl in package.json eintragen

Der Kurzbefehl heißt hier ver (für „veröffentlichen“) und bündelt alle Optionen.

nano package.json

Suche mit Strg+W nach "scripts" und bestätige mit Enter. Füge in der Zeile darunter diese Zeile ein (im Terminal mit Strg+Umschalt+V). Steht danach noch ein weiterer Eintrag wie "test", muss die Zeile mit einem Komma enden. Speichere mit Strg+O und Enter und beende nano mit Strg+X:

    "ver": "gh-pages -d book --nojekyll --cname installieren.wissen-ahrensburg.de --no-history"

Die Optionen bedeuten:

  • -d book – veröffentlicht den Ordner book, in den mdbook build schreibt
  • --nojekyll – verhindert, dass GitHub die Seite mit Jekyll aufbereitet (siehe Schritt 10 oben)
  • --cname installieren.wissen-ahrensburg.de – legt die Datei CNAME mit dieser Domain in den Branch. Daran erkennt GitHub, unter welcher Domain es die Seite ausliefern soll. Ersetze sie durch deine eigene (Sub-)Domain.
  • --no-history – ersetzt den Branch gh-pages bei jeder Veröffentlichung durch einen einzigen neuen Commit, statt einen weiteren anzuhängen. Das Repository wächst dadurch nicht mit jeder Veröffentlichung. Ältere Stände der Webseite sind danach nicht mehr im Branch gh-pages gespeichert; die Quelltexte in main bleiben unberührt.

Der Abschnitt scripts sieht danach z. B. so aus:

  "scripts": {
    "ver": "gh-pages -d book --nojekyll --cname installieren.wissen-ahrensburg.de --no-history"
  },

Prüfen: npm listet den Kurzbefehl ver auf.

npm run

2. Ordner book von Git ausschließen

book wird bei jedem Bauen neu erzeugt und gehört nicht in den Branch main. Öffne dazu .gitignore:

nano .gitignore

Füge diese Zeile ein, falls sie noch fehlt, speichere mit Strg+O und Enter und beende nano mit Strg+X:

book

3. DNS-Eintrag für die Subdomain setzen

Einmalig beim Anbieter deiner Domain: Die Subdomain muss auf GitHub Pages zeigen. Lege dazu einen CNAME-Eintrag an:

NameTypZiel
installierenCNAMEthorstenkloehn.github.io

Ersetze thorstenkloehn durch deinen GitHub-Namen. Der Eintrag verweist nur auf deine GitHub-Adresse, nicht auf das Repository. Welches Repository gemeint ist, erkennt GitHub an der Datei CNAME aus Schritt 1.

Prüfen: Nach einiger Zeit (je nach Anbieter Minuten bis Stunden) nennt dieser Befehl zuerst thorstenkloehn.github.io. und danach die Adressen von GitHub, die mit 185.199. beginnen.

dig +short installieren.wissen-ahrensburg.de

Fehlt dig, installierst du es mit sudo apt install bind9-dnsutils.

Hauptdomain statt Subdomain: Soll die Seite direkt unter wissen-ahrensburg.de erscheinen, ist ein CNAME-Eintrag bei vielen Anbietern nicht erlaubt. Dann legst du stattdessen vier A-Einträge mit den Adressen 185.199.108.153, 185.199.109.153, 185.199.110.153 und 185.199.111.153 an und gibst bei --cname die Hauptdomain an.

4. Buch bauen

Erzeugt den Ordner book mit der aktuellen Fassung aller Anleitungen. Ohne diesen Schritt würde gh-pages einen veralteten oder gar keinen Stand veröffentlichen.

mdbook build

Prüfen: Im Ordner book liegt eine index.html.

ls book/index.html

5. Buch veröffentlichen

Führt den Kurzbefehl aus Schritt 1 aus.

npm run ver

Prüfen: Die Ausgabe endet mit Published. Der Branch gh-pages enthält jetzt genau einen Commit:

git fetch origin gh-pages

git log --oneline origin/gh-pages

6. Eigene Domain in GitHub bestätigen

Einmalig im Browser: Öffne im Repository Settings → Pages. Stelle wie in Schritt 13 oben den Branch gh-pages ein. Unter Custom domain steht nun installieren.wissen-ahrensburg.de (aus der Datei CNAME). Setze, sobald GitHub es anbietet, den Haken bei Enforce HTTPS, damit die Seite verschlüsselt ausgeliefert wird.

Prüfen: https://installieren.wissen-ahrensburg.de/ zeigt das Buch.

Bei jeder späteren Änderung genügen die Schritte 4 und 5. Weil die Seite direkt unter der Subdomain liegt und nicht unter /meine-seite/, ist in mdBook keine zusätzliche Pfadangabe nötig.

Aktualisieren

gh-pages wird pro Projekt aktualisiert. Im Projektordner holt dieser Befehl die neueste Version innerhalb von gh-pages 6:

npm update gh-pages

Prüfen:

npm ls gh-pages

Fehlerbehebung

Meldet gh-pages Remote url mismatch, hat sich die Adresse von origin geändert, seit der Zwischenspeicher angelegt wurde. Dieser Befehl leert den Zwischenspeicher, danach funktioniert npm run deploy wieder:

npx gh-pages-clean

Deinstallieren

1. gh-pages aus dem Projekt entfernen

Löscht gh-pages aus node_modules und aus package.json.

npm uninstall gh-pages

Prüfen: Die Ausgabe zeigt (empty).

npm ls gh-pages

2. Kurzbefehl entfernen

Die Einträge deploy bzw. ver funktionieren ohne gh-pages nicht mehr.

nano package.json

Suche mit Strg+W nach "deploy" (bzw. "ver"), lösche die Zeile mit Strg+K, speichere mit Strg+O und Enter und beende nano mit Strg+X.

3. Optional: Veröffentlichte Webseite löschen

Entfernt den Branch gh-pages auf GitHub. Achtung: Die Webseite ist danach nicht mehr erreichbar.

git push origin --delete gh-pages

4. Optional: Node.js und npm entfernen

Nur ausführen, wenn kein anderes Programm Node.js braucht (z. B. VitePress oder Docusaurus).

sudo apt purge nodejs npm

sudo apt autoremove

Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).

Open Knowledge (Freies Wissen): Alle Texte stehen unter der freien Lizenz Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) und können frei gelesen, geteilt und weiterverarbeitet werden.

Hinweis: Diese Inhalte wurden mit Unterstützung von Künstlicher Intelligenz erstellt und redaktionell überprüft (Transparenzhinweis gemäß Art. 50 EU AI Act).

Open Knowledge (Freies Wissen): Alle Texte stehen unter der freien Lizenz Creative Commons Namensnennung – Weitergabe unter gleichen Bedingungen 4.0 International (CC BY-SA 4.0) und können frei gelesen, geteilt und weiterverarbeitet werden.

Autor: Thorsten · Installationsanleitungen für Ubuntu

Alle Anleitungen ohne Gewähr. Befehle mit sudo verändern das System – vorher lesen, dann ausführen.