07 | Webprojekte mit Hugo realisieren

Hugo ist ein statischer Webseitengenerator, mit dem sich verschiedenste Projekte umsetzen lassen. Mit einem stark reduzierten Beispielprojekt fällt der Einstieg leicht.

Ziele

  • Sie installieren Hugo auf Ihrem Rechner.
  • Sie importieren, forken und klonen das Beispielprojekt.
  • Sie halten Entwicklungsziele in Issues fest.
  • Sie passen das Beispielprojekt an verschiedenen Stellen an, um es für Ihre Zwecke nutzbar zu machen.
  • Sie arbeiten über Forks und Pull requests zusammen. Dabei synchronisieren Sie Ihren Fork regelmäßig mit den Upstreamentwicklungen.

Ein Beispielprojekt in Hugo

Hugo ist ein Programm zum Generieren von Webseiten. Es zählt zur Klasse der static site generators, also den statischen Webseitengeneratoren. Davon gibt es eine Menge, deren Grundprinzip immer dasselbe ist: Aus einfachen Textdateien, in den meisten Fällen Markdown-Dateien, generieren diese Programme statische HTML-Seiten. Diese Konstrukte sind sehr schnell, stellen keine großen Ansprüche an den Webserver und sind kaum angreifbar.

Statische Webseitengeneratoren sind vor allem in Python, Go, Ruby oder JavaScript geschrieben. Ihr Gebrauch ist unterschiedlich komplex. Die größte Lernkurve liegt in der Erstellung von Themes, Layouts und Templates, weil dafür die Kenntnis weiterer Template-Sprachen notwendig ist.

Hugo ist für seine Geschwindigkeit und Flexibilität bekannt. Auch viele hundert Seiten werden binnen Sekunden zu komplexen statischen HTML-Konstrukten gewandelt, wie dieser Bericht des bekannten Smashing Magazines zeigt.

Aufbauend auf dem Theme Etch von Lukas Joswiak wird hier eine angepasste Variante für dieses Lernangebot bereitgestellt. Neben der Möglichkeit, mit dem Theme zu bloggen, enthält es eine beispielhafte Karte mit Markern. An diesem Feature soll gezeigt werden, wie mit Hugo strukturierte Daten verarbeitet werden können.

Screenshot der beispielhaften Karte
Screenshot der beispielhaften Karte

Sie finden das Repo auf GitHub.

Erläuterung der Dateistruktur

Der Dateibaum entspricht weitestgehend dem Standard eines Hugo-Projekts. Es wurden jedoch noch einige Ordner und Dateien ergänzt, mit denen sich das Beispielprojekt in eine eigene Richtung entwickeln oder sogar schon als Grundlage für eigene Projekt nehmen lässt.

Darstellung einer Auswahl von Dateien und Ordnern im Beispielprojekt
Darstellung einer Auswahl von Dateien und Ordnern im Beispielprojekt

Die folgende Aufzählung bezieht sich auf die Nummern in der Abbildung des Dateibaums:

  1. custom.css: Überschreiben des CSS’, das vom Theme mitgeliefert wird.
  2. content/_index.md: Inhalte der Homepage
  3. content/map/index.md: Beispiel einer Unterseite. Im YAML-Frontmatter der Datei wird mit type: map auf die Templatedatei layouts/map/single.html verwiesen.
  4. content/posts/: Sammlung von Markdown-Dateien für die Blogabteilung.
  5. data/places/: Sammlung von YAML-Dateien mit Daten für die Marker der Karte, pro Marker eine Datei.
  6. layouts/map/single.html: Für dieses Projekt entwickelte Templatedatei, die das Partial layouts/partials/place.html einbindet.
  7. layouts/partials/: Sammlung von partiellen Templatedateien, die in Templates eingebunden werden können. Ihr Sinn und Zweck ist die Wiederverwendbarkeit in unterschiedlichen Kontexten.
    layouts/partials/place.html: Genutzt, um für jede YAML-Datei in data/places/ das Markup für einen Marker auf der Karte zu generieren.

Einsatz von Leaflet.js

Für die Darstellung der Karte auf der Seite wird Leaflet.js verwendet. Damit die notwendige CSS- und JavaScript-Datei geladen wird, wurde die Datei layouts/partials/head.html aus dem ursprünglichen Theme kopiert und erweitert.

Die Karte wird in layouts/map/single.html initialisiert. Marker werden darin mithilfe einer Schleife und dem Partial layouts/partials/place.html als separate <script>-Fragemente generiert. Dabei wird auf die Dateien in data/places/ zugegriffen. Jede dieser YAML-Dateien enthält die entsprechenden Informationen für einen Marker auf der Karte.

meta:
  title: Altonaer Balkon
  lat: 53.54529
  lon: 9.93581
  popuptext: |
    Have a nice view from here.    

Diese Informationen werden in die Platzhalter des Partials layouts/partials/place.html eingefüllt:

<script type="text/javascript">
  L.marker([
      {{ .meta.lat }},
      {{ .meta.lon }}],
      {
          "title": {{ .meta.title }}
        }
    ).addTo(map)
      .bindPopup('{{ .meta.popuptext }}')
</script>

Weiterführende Informationen

Aufträge

Repo importieren, forken und klonen

Das Kartenbeispiel auf Hugo-Basis dient dazu, die nächsten Schritte eigenverantwortlicher Arbeit in Teams zu üben.

  1. Alle Maintainer*innen: Importieren Sie das Repo hugo-map-example in den Namespace participatoryplayground, wie auf dem Screenshot zu sehen. Den Import stoßen Sie an über das Pulldownmenü in der oberen Navigationsleiste rechts:

    Screenshot: Import eines Projekts von GitHub in GitHub
    Screenshot: Import eines Projekts von GitHub in GitHub
    Vergeben Sie beim Import einen neuen Namen für das neue Repository:
    Screenshot: Einstellungen und Namensgebung beim Import
    Screenshot: Einstellungen und Namensgebung beim Import
  2. Maintainer*innen: Fügen Sie das neue Repository Ihrem Team hinzu.

  3. Alle Rollen in den Teams: Forken Sie das neue Repo in Ihren persönlichen Account. Klonen Sie den Fork anschließend auf Ihren Rechner.

  4. Sorgen Sie dafür, dass die Website lokal mit Hugo gebaut wird. Der Befehl zum Starten des Hugo-Entwicklungsservers lautet hugo serve. Rufen Sie die Seite in Ihrem Browser auf.

Warum importieren?
Vielleicht fragen Sie sich, warum Sie das Beispielrepo importieren und nicht forken sollen. Der Import bietet in diesem Szenario die Möglichkeit, die Kopie umzubenennen und zu individualisieren. Mit einem Fork gäbe es nur eine Kopie in unserem Team, und diese ließe sich nicht für die einzelnen Projektideen abändern.

Anpassungen vornehmen und zusammenarbeiten

Nehmen Sie nun im Team Änderungen an dem Kartenbeispiel vor, die durch Ihre Projektidee motiviert werden.

  1. Notieren Sie alle Anpassungswünsche in jeweils einem Issue. Die Issues sollten im Basis- bzw. Upstream-Repository erstellt werden, nicht in den jeweiligen Forks! Besprechen Sie anschließend, wer was macht. Folgende Änderungen sollen Sie in jedem Team vornehmen:
    • Name der Website
    • Inhalte der Homepage
    • Informationen im Footer
    • Ersetzen der Beispielposts durch eigene
    • Verlinkung von Markern mit Blogposts
    • Geokoordinaten und Zoomgrad für das Zentrum der Karte
    • Überschrift der Karte
    • Ergänzen von mindestens einem neuen Marker pro Teammitglied
    • Anpassungen im CSS
    • Anlegen einer neuen Seite (zusätzlich zu “posts” und “map”) und Verlinkung dieser in der Navigation
  2. Erarbeiten Sie einen Workflow im Team, bei dem Ihre Änderungen häufig von den Maintainer*innen integriert werden. Aktualisieren Sie Ihre Forks in möglichst gleicher Frequenz und pullen Sie regelmäßig.
    Regel: Immer erst pullen, dann pushen!

Zurück