Umzug von DokuWiki nach Hugo – Teil 1 – Vorarbeiten

Ich habe ein klares Ziel: Ich möchte auch mein Wiki in eine Webseite mit statischen Dateien umwandeln. Aktuell verwende ich die in PHP geschriebene Software DokuWiki für mein Wiki.

Es gibt zwar Export-Tools von DokuWiki nach Markdown (und damit hin zu Hugo), doch der Einsatz solcher Tools ist mit sehr viel Mehrarbeit nach dem Export der Daten verbunden. Hier habe ich bereits die verfügbaren Lösungen ausprobiert.

Und in meinem Fall ist es extrem viel Mehrarbeit, da mein Wiki aus vielen hundert Seiten besteht. Alleine meine Mumble-Dokumentation besteht aus über 350 Seiten.

Daher habe ich mich für Folgendes entschieden:

• Ich fange ein neues Wiki an. Mit Hugo und einem Theme, das für Dokumentationen gemacht wurde, wie z. B. Docsy, mit dem auch die Dokumentation des OpenBikeSensors zur Verfügung gestellt wird.
• Neue Inhalte werde ich ab sofort nur noch ins neue Wiki einfügen.
• Inhalte aus dem alten Wiki, die noch “aktiv” sind, werde ich nach und nach umziehen und am alten Ort auf den neuen Ort verlinken.
• Diese aktuell “aktiven” Inhalte werden dann erst einmal “Sport” bzw. “Fahrrad” und “Verkehr” bzw. “Mobilität” sein. Danach vermutlich “Müllsammeln”.
• Irgendwann werde ich das alte Wiki auf “Readonly” umstellen oder sogar mit Hilfe von z. B. wget in eine statische Website umwandeln, so wie damals mit meinem alten MediaWiki.

Was das alte Wiki hat und was das neue Wiki erfüllen muss

Ich habe angesehen, welche Formatierungen im alten Wiki verwendet werden, welche Plugins installiert sind, welche Funktionen ansich wichtig sind und was ein Theme für das neue Wiki können sollte.

Basis-Formatierungen

Alle Basis-Formatierungen aus DokuWiki (solche, für die keine Plugins benötigt werden), die ich in meinem bisherigen Wiki verwende, stehen so auch von Haus aus in Hugo zur Verfügung und werden auch von entsprechenden Tools automatisch konvertiert.

Verwendete Plugins von DokuWiki, deren Funktionalität ersetzt werden muss (oder nicht)

Das hier ist die Liste der Plugins, die in meinem DokuWiki verwendet werden. Ich bin sie durchgegangen und habe geprüft, ob es einen Ersatz für Hugo gibt oder ob ich die Funktionalität überhaupt noch benötige.

• Anchor – Damit kann man Anker an bestimmten Punkten erstellen. Ich nutze das für Überschriften, auf die ich von extern verlinken möchte. In Hugo ist das automatisch für jede Überschrift möglich.
• DokuTeaser – Verwende ich nur auf der Startseite und brauche das im neuen Wiki gar nicht mehr.
• Gallery – Eine Bildergalerie. Gibt es für Hugo, aber wäre schön, wenn das Theme das selbst könnte und ich es nicht implemtieren müsste. Habe ich aber bisher im Wiki auch nur aus Faulheit verwendet in ein paar Fällen. Brauche ich eigentlich nicht. Einbindung von Einzelbildern hintereinander ist ausreichend.
• hidden – Klappt einen Bereich erst nach einem Klick auf “Anzeigen” aus. Hier habe ich einen eigenen Shortcode für den Blog erstellt mit dem Namen details, den ich auch im Wiki verwenden kann, falls ich ihn irgendwann doch mal benötigen sollte.
• Imagebox – Einfache Box für Bilder mit der Option für Untertitel. Hier kann ich einen eienen figure shortcode aus meinem Blog benutzen.
• Include – Verwende ich nur für, um in bestimmten Seiten über Produkte den Disclaimer einzufügen. Hier kann ich den Shortcode disclaimer aus dem Blog verwenden.
• Indexmenu – Wunderschöne Baumansicht fürs Wiki. Leider ist die schöne Ansicht nur mit JavaScript verfügbar. Hier werde ich die Defaultansicht des Hugo-Themes nutzen, die mir dann ausreichen wird.
• keyboard – Zum Verdeutlichen von Tastenkombinationen – Kann ich sehr einfach als Shortcode selbst umsetzen.
• Move Plugin – Kümmert sich beim Verschieben von Seiten innerhalb des Wikis um das Anpassen der relativen Links auf andere Seiten und Bilder im Wiki. Kann man selbst implementieren für Hugo.
• Pagelist – Dieses Plugin wird benötigt, damit die Liste der Tags im Wiki funktioniert.
• Page Navigation Plugin – Habe ich nur ganz selten und ausschließĺich früher in der Mumble-Dokumentation verwendet und benötige das nicht mehr. Ließe sich einfach als Shortcode erstellen.
• Page Query Plugin – Das könnte mir fehlen. Ein sehr mächtiges Plugin, um z. B. alle Seiten eines besimmten Namensraums als Liste in einer Wikiseite einzufügen, deren Seitennamen bestimmte Bedingungen erfüllen. Möglicherweise könnte ich für rudimentäre Funktionen sowas wie ToC nutzen (siehe unten). Ein interessanter Shortcode dafür könnte toc-tree sein.
• Redirect Plugin – Hugo hat von Haus aus Aliases, die man im Front Matter eintragen kann, um eine Seite nach dem Umzug noch am alten Ort erreichbar zu haben.
• SocialCards Plugin – Kümmert sich um das Hinzufügen von Metadaten für Twitter Cards und Open Graph. Sollte das Theme in Hugo unterstützen, da wichtig fürs Teilen von Inhalten auf SocialMedia.
• sortablejs – Damit wird ermöglicht, dass Tabellen sortierbar werden. Kann ich drauf verzichten, da nicht unbedingt notwendig. Eventuell sogar selbst anhand des Codes implementierbar.
• Tag Plugin – Tags gibts in Hugo von Haus aus.
• Translation Plugin – Gibts in Hugo von Haus aus. Muss nur vom Theme unterstützt werden.
• Wrap Plugin – Infobox, Warnbox, … und auch ein clear Container. Für das alles habe ich schon selbst im Blog einem Shortcode umgesetzt, den ich auch hier verwenden kann.

Versionierung

DokuWiki hat eine Versionshistory für jede einzelne Seite. Das geht auch mit Git, zwar nicht über die Website sondern nur in der Shell, aber das reicht mir. Im DokuWiki hatte ich die Funktion für unangemeldete Benutzer sowieso deaktiviert und selbst nie genutzt.

Optional kann man in Hugo aktivieren, dass Daten aus Git auslesbar werden und innerhalb verschiedener Seiten angezeigt werden können, wie z. B. die letzte Änderung einer Seite. Details siehe Git in Hugo.

Funktionen, die ein Theme für Hugo haben sollte

• Inhaltsverzeichnis für jede Seite.
• Hell- und Dunkel-Modus wären schön. Im aktuellen Wiki wird das verwendet, was im Browser eingestellt wurde, es lässt sich aber nicht in einem Menü des Wikis umschalten.
• Mehrsprachigkeit – Aus historischen Gründen habe ich ein paar Seiten in Englisch im Wiki. Ist keine Notwendigkeit, aber Hugo hat das eh schon von Haus aus.
• Breadcrumbs wären schön.
• Keinerlei Einbindungen von externen Elementen.

Getestete Themes

Ich wollte hier nachvollziehbar machen, weshalb ich mich für ein Theme entschieden habe. Da ich aber direkt mit Docsy anfing und das (fast) alles kann, was ich brauche, gibt es zum Vergleich nur noch Geekdocs. Vielleicht hilft es ja jemandem 🙂, der ein Theme sucht.

Neue Möglichkeiten

Wenn das Repo des neuen Wikis z. B. auf Github liegen würde, dann könnte jeder Mensch mit einem Account dort einen Fehler im Wiki melden oder direkt selbst korrigieren.

Entscheidung

Ich habe mich für das Theme Docsy entschieden.