Anleitung: Wiki erstellen mit Github Pages

Ich bin mir nicht 100% sicher ob hier der beste Ort dafür ist, aber vielleicht hilft es ja jemandem

Einleitung

Ein oft geäußerter Wunsch von Communities hier auf feddit und dem threadiverse allgemein ist es, doch Wikis anzubieten. Lemmy bietet diese Funktionalität zum gegenwärtigen Zeitpunkt nicht. Diese Anleitung soll eine Option näherbringen ein solches Wiki zu erstellen. Es ist nicht die einzige Option, aber es ist die, die ich gewählt habe als ich ein Wiki für die Germany Community gebaut habe und ich dachte mir, möglicherweise haben noch Andere ein Interesse, daran meine Arbeit zu replizieren.

Es wird kein Programmierwissen vorausgesetzt, lediglich Markdown-Kenntnisse sollten vorhanden sein. Hinweis: Reddit-Wikis lassen sich relativ einfach rüberkopieren, aber nicht ohne etwas manuelle Arbeit. Reddit spricht einen etwas vergebenderen MD-Dialekt als dieses System, etwas Fomatierung muss also manuell angepasst werden.

Rein technisch gesehen ist das was wir hier machen kein Wiki. Es erfüllt aber die Anforderungen eines Wikis für Communities.

Der Tech-Stack

Jekyll

Das System im Hintergrund der Seite ist Jekyll, ein so genannter “Static-Site-Generator”. SSGs sind sehr flexible Systeme, die allerdings keinen visuellen Editor zum bearbeiten der Seite mitbringen. Stattdessen werden Posts und Seiten als Markdown-Dokument verfasst und dann von Jekyll automatisch zu HTML umgewandelt. Aber keine Sorge: Wir rüsten einen rudimentären Editor nach mittels

Github & Github Pages

Github ist eigentlich eine Plattform für das Teilen und Verwalten von Programm-Quellcode. Seine Oberfläche wird uns aber auch die Möglichkeit bieten, die Website direkt im Browser zu bearbeiten (Und an alle die häufiger mit Github arbeiten: Ich entschuldige mich im Voraus für einige der Dinge, die ich im Namen der Einsteigerfreundlichkeit beschreiben werde). Mit Github Pages können wir die Seite auch noch direkt kostenlos hosten. Dabei werden wir eine Internetadresse nach dem Schema [githubnutzername].github.io/projektname haben. Wer seinen persönlichen Nutzernamen nicht als Teil der Domain haben möchte, der kann eine Github Organisation anlegen. Mit der wird der Name in der Adresse durch den der Organisation ersetzt.

Github hat den Vorteil, das man nicht auf einen Anbieter festgelegt ist. Sollte Github einmal Probleme bereiten, lässt sich die Seite relativ einfach auf Gitlab oder einen anderen Git-Hoster umziehen.

Schritt-für-Schritt-Anleitung

1.

Lege dir einen Github Account an und erstelle gegebenenfalls eine neue Organisation

2.

Wähle ein Theme aus. Du willst ein Dokumentations-Thema verwenden. Für diese Anleitung werden wir ein Thema mit dem Namen “Just the Docs” verwenden. Um eine mit diesem Thema vorkonfigurierte Seite zu erstellen klicke diesen Link an.

3.

Lege den Projektnamen (in Github-Sprech Repository Name) fest. Gebe außerdem an, ob Du oder die Organisation das Projekt verwalten soll. Beides kann später noch geändert werden. Setze das Projekt auf “öffentlich”. Mit Privaten Projekten funktioniert die Website nicht. Klicke dann auf “Create repository from template”

Herzlichen Glückwunsch, deine Seite ist nun Online

Du kannst die mittels deiner gewählten Adresse (am besten in einem neuen Tab) jetzt aufrufen. Wenn das nicht funktioniert warte einfach ein paar Minuten. Möglicherweise braucht der Server etwas um alles fertigzustellen.

4.

Was du nun vor dir hast, ist eine Ansicht aller Dateien, die für den Server wichtig sind. Jetzt gilt es die richtigen zu bearbeiten. Da ist zum einen _config.yml. In dieser Datei kannst du den Titel der Website bearbeiten. Außerdem kannst du unter aux_links einen Link zur Lemmy-Comunity unterbringen und den Link zum Theme herauslöschen (Bitte lösche den Link nur unter aux_links und nicht unter url).

Zum Bearbeiten klicke einfach auf die Datei und dann auf den Stift oben rechts in der Ecke der Dateiansicht. Zum Speichern klicke auf “Commit changes”. Als Admin kannst du direkt speichern (“Commit directly into the main branch”, für alle anderen bietet sich an, die Änderungen nur Vorzuschlagen und dann auf die Akzeptanz eines Admins zu warten. (Wie sich das einrichten lässt geht ein bisschen zu weit für diesen Guide, möglicherweise reiche ich das später noch einmal nach)

Alle Änderungen werden direkt online gesetzt.

5.

Die Startseite wird in der Datei index.md definiert. Aktuell beinhaltet sie eine Menge Beispieltext. Ersetze ihn durch deine eigenen Inhalte im Markdown-Format.

Ganz oben am Beginn des Dokumentes gibt es einige Konfigurationsparameter. Im Jekyll-Jargon heißt das “Frontmatter”. Im Frontmatter wird festgelegt, unter welchem Namen die einzelne Seite, der einzelne Eintrag in der Navigation auf der linken Seite erscheinen soll (title), das layout der Seite (nimm einfach immer default), ob es Unterseiten gibt (has_children: true), ob die Seite eine Unterseite ist (parent: Name der Oberseite), An welcher Position der Eintrag im Menü ist (nav_order, wird der nicht gesetzt werden die Seiten Alphabetisch geordnet). All diese Parameter werden von jeweils drei Bindestrichen eingerahmt. Jede Seite braucht Frontmatter, aber nicht alle Parameter werden immer gebraucht Jede Seite sonnte immer einen Titel und ein Layout haben, der Rest ist optional. Für die Startseite empfehle ich zusätzlich noch die nav_order: 1 zu setzen, um Sicherzustellen, das die Seite immer ganz oben im Menü steht.

6.

Um neue Einträge hinzuzufügen klicke auf Add file > Create new file. Gib den Dateinamen an. Denke dabei auch an die Endung (.md). Der Dateiname muss nicht mit dem Titel der Seite übereinstimmen, er sollte aber nicht zu weit abweichen, damit man die Datei später wiederfindet. Standardmäßig werden alle Dateien einfach im Wurzelverzeichnis gespeichert. Um mehr Übersicht zu schaffen bietet es sich an die Einträge in Ordner und Unterordner zu sortieren. Dafür gibst du im Dateinamen-Feld den Naben des Orners gefolgt von einem Slash (/) ein. Sollte der Ordner nicht existieren, so wird er automatisch angelegt, sobald die Datei Commited wird. Denke an die Frontmatter!

Und das wars schon! Meldet euch bei Fragen; ich helfe gerne, wo ich kann. Über Anmerkungen und Ergänzungen bin ich auch dankbar.

Die offizielle Dokumentation für das Theme gibt es hier: https://just-the-docs.github.io/just-the-docs/