Statische Seite mit Hugo!
Hugo installieren (Version > 0.51):
https://gohugo.io/getting-started/installing
Wenn du das Hugo binary manuell installierst, achte darauf die extended
version zu nehmen, da diese auch Sass kompilieren kann
Developement Server laufen lassen:
$ hugo serve
Dann auf localhost:1313
die Seite anschauen. (Die Suche wird hier nicht funktionieren, weil die Indexe fehlen)
Seite und dann Indexe bauen.
$ hugo && \
cat public/index.json | node scripts/lunr/site-index.js > public/js/site-search-index.json && \
cat public/blog/index.json | node scripts/lunr/blog-index.js > public/js/blog-search-index.json && \
echo "Done"
Dann in /public
einen HTTP-Server starten.
Ein Push zu GitHub genügt um den Buildprozess anzustoßen. Im Normalfall musst du dich um nichts kümmern und deine Änderungen sind in ein paar Minuten online.
Falls das nicht passiert, findest du unten unter 'Anderes' und 'Buildprozess' mehr Infos.
Alle Blogposts befinden sich in content/blog/
und nach Jahren organisiert.
Ein Beispiel für einen neuen Blogpost findest du in archetypes/post.md
.
Erstelle eine neue Datei in content/blog/<jahr>/
und kopiere die Dummydaten aus der Archetypesdatei.
authors
: eine Liste der Autorendate
: das Veröffentlichungsdatum. Wird zur Sortierung benutztimage
: ein Bild das in Social Media Links angezeigt wird und optional bei Featured (siehe unten). Bitte achte auf angemessene Bildgrößen! Ein Bild direkt von Flickr oder deiner Kamera ist in den meisten Fällen viel zu groß!tags
: eine Liste von Tagstype
undlayout
für intere Sachen. Bitte nicht verändernpublished
: ob der Post veröffentlicht werden soll,true
oderfalse
title
: der Titel des Postsfeatured
: siehe unten
Featured ist ein neues Feature.
Auf der Startseite und auf der ersten Seite des Blogs wird ein Blogpost gefeatured, d.h. groß und mit buntem Hintergrund und Bild angezeigt.
Die Logik hinter Featured ist, das immer der aktuellste Post, bei dem featured
gesetzt ist, als feature erscheint. Dein POst soll nicht gefeatured werden? Lösche featured
aus deinem Post.
featured
kann zwei Werte haben yellow
und blue
, die einen gelben oder blau/türkisen Hintergrund definieren.
Alle Teammitglieder und Vorstände sind in data/team.yml
zu finden.
Um ein neues Mitglied hinzuzufügen, kopiere einen Listeneintrag (oder das leere Beispiel) und setze ihn an das Ende der Datei. Die folgenden Felder werden unterstützt:
- name:
title:
img:
staff: 1
board: 0
advisory: 0
position:
position_en:
bio:
bio_en:
mail:
twitter:
mastodon:
website:
Die 0 und 1 werden als true und false Werte behandelt. Sprich, staff: 1
bedeutet aktives Teammitglied, staff: 0
bedeutet ehemaliges Teammitglied
Die Übersetzungen der Bio und der Position sind direkt hier mit dabei.
img
sollte dem Namen der Bilddatei entsprechen, die du in static/team
als .jpg
ablegst. Bitte achte darauf keine gigantischen Bilder zu benutzen, denn Nutzer wollen nicht 2 Minuten auf ein Bild warten. 300 x 200 Pixel in guter Qualität sind absolut ausreichend.
Alle Projekte befinden sich unter content/projekte
.
Dabei hat jedes Projekt zwei Dateien, eine deutsch- (.md
) und eine englischsprachige (.en.md
).
Lege in content/projekte
zwei Dateien an: einproject.md
und deinproject.en.md
.
In archetypes/project.md
findet du die Beispiel mit Felder, die ein Projekt haben kann.
Hier kurz Erklärungen zu den einzelnen Feldern:
title
ist der Name des Projektessubtitle
is die Taglinekategorien
is nur für die deutschsprachige Seite wichtig und kann auf der englischen gelöscht werden. Es soll eine Liste mit ein oder mehreren Kategorien sein, nach denen auf der Projektseite gefiltert werden kanncategories
ist nur für die englischsprachige Seite wichtig und kann auf der deutschen gelöscht werden. Es soll eine Liste mit ein oder mehreren KAtegorien sein, nach denen auf der englischen Projektseite gefiltert werden kann.tile
bestimmt wie das Projekt auf der Projektübersichtsseite dargestellt wird.Single
beschreibt eine kleine Fläche,double
die doppelt so große. Soll ein Projekt nur unter "Weitere Projekte" gelistet werden, dann kannst du dieses Feld löschenwebsite
die url zur Website des Projektes
Jobs sind nun getrennt von Blogposts, bekommen aber trotzdem eine eigene Seite, die verlinkt und geteilt werden kann.
Um eine neue Stellenaussschreibung hinzuzufügen, musst du in content/jobs
eine neue Markdown-Datei anlegen.
In archetypes/jobs.md
kannst du dir eine Vorlage für das Markdown ansehen, kopieren und anpassen.
Um das Jobposting zu entfernen, einfach die entsprechende Markdown-Datei löschen.
Unter /verein
sind einige Fakten in Zahlen angegeben. Diese befinden sich in /content/verein.md
und content/verein.en.md
unter dem Key 'stats'. Unter diesem Key gibt es eine Liste aus Schlüssel/Wertpaaren die immer eine Zahl und einen Text dazu definieren. Diese können beliebig verändert werden.
Ebenfalls auf /verein
befinden sich die herunterladbaren Jahresberichte bzw Tätigkeitsberichte. Diese werden in /data/jahresberichte.yml
definiert. Pro Eintrag gibt es immer:
year
das Jahr des jeweilgen Jahresberichtesimg
ein Pfad zum Teaserbildpdf
ein Pfad zum Jahresbericht als PDF zum downloads- jeweils
title
undtext
under den Sprachoptionen
!!Achtung: Den aktuellen Bericht keinesfalls schon auf der Webseite verlinken, bevor nicht 1. die Mitgliederversammlung ihn abgesegnet hat und 2. der Wirtschaftsprüfer die Zahlen freigegeben hat!!
Sobald das passiert ist: Für einen neuen Eintrag, einfach einen alten kopieren, an den Anfang der Datei setzen (es wird nicht extra sortiert, die Reihenfolge in der Datei ist wichtig) und anpassen.
Der letzte Abschnitt auf /verein
listet verschiedene herunterladbare Dokumente, die die Organisation als Verein betreffen.
Diese sind under /data/downloadsverein.yml
definiert und können dort auch angepasst und verändert werden. Es gibt die Felder title
und text
jeweils auf deutsch und englisch und dann path
der Pfad zur herunterladbaren Datei.
Auf der Finanzseite gibt es mehrere Grafiken, die die Entwicklung und Einnahmen/Ausgaben aufschlüsseln.
Unter /finanzen
befinden sich die herunterladbaren Jahresabschlüsse und Berichte der Wirtschaftsprüfung. Diese werden in /data/downloadsfinanzierung.yml
definiert.
- Jeweils
title
undtext
under den Sprachoptionen, wie sonst auch. - Ein Eintrag mit nur einer verlinkten Datei setzt einen Link mittels
path
- Mehrjährige Einträge definieren mit
years
eine Liste an Jahren, die gleichzeitig das Ende eines Dateinamen bilden und einprefix
mit Pfad und Dateinamenanfang.- Beispiel:
prefix: /pfad/zur/datei
wird mit einem Eintrag für 1984 in der liste anyears
zu einem Link auf/pfad/zur/datei-1984.pdf
.
- Beispiel:
Das zugehörige Partial template ist zur Zeit unter layouts/partials/downloads/finanzierung.html
zu finden.
Für einen neuen Eintrag, einfach einen alten kopieren, an den Anfang der Datei setzen (es wird nicht extra sortiert, die Reihenfolge in der Datei ist wichtig) und anpassen.
Die Grafiken werden dynamisch aus CSV-Dateien erstellt, die sich in /static/okf/finanzierung
befinden.
Pro Grafik existiert eine CSV-Datei, deren Inhalte jeweils angepasst werden können. Die Dateinahmen und das Schema dürfen nicht verändert werden, weil sonst das Script kaput geht.
Ebenfalls auf der Finanzierungsseite zu finden sind weitere Downloads. Diese sind in /data/downloadsfinanzierung.yml
festgehalten. Sie funktionieren wie die anderen Downloads auch mit der Ausnahme des letzen Eintrags. Hier gibt es eine Liste der Gewinn- und Verlustrechnungen der vergangenen Jahre, die anstelle eines kleinen Beschreibungstextes aufgeführt werden. Damit das (auch für weitere Jahre) funktioniert, müssen diese unter /static/files/documents/OKF-DE-Gewinnermittlung-kurz-<jahr>.pdf
abgelegt werden. Dabei ist <jahr>
mit dem entsprechenden Jahr zu ersetzen.
Alle Inhalte, abgesehen von Blogposts, sind auf deutsch und englisch vorhanden.
In den meisten Fällen wird eine Markdowndatei .md
mit einem äquivalenten, aber übersetzten .en.md
bereitgestellt.
Manchmal, gerade wenn Informationen in /data
als yml liegen, gibt es Übersetzungsspezifische Keys.
Templateübersetzungen finden sich in /i18n/
.
Alle Bilder, PDFs oder sonstige Assets kannst du in /static
ablegen.
Während des Buildprozesses wird der Inhalt von /static
direkt in das Roorverzeichnis kopiert.
Was heißt das für die Dateipfade?
Ein Bild das in /static/bild.png
liegt wird direkt unter okfn.de/bild.png
verfügbar sein. Also die Ordnerstruktur bleibt die gleiche, /static
am Anfang muss weg.
Du kannst für einen Post oder eine Seite einen 'Alias' anlegen. Hugo wird dann von diesem Alias auf die aktuelle Seite weiterleiten. Das funktioniert über das aliases:
keyword im Frontmatter.
aliases:
- /blog/old-post-url/
- /blog/maybe-even-older/url/
Alle notwendigen externen Abhängigkeiten sind extra in js/vendor oder sass/vendor eingecheckt.
Das hat den Vorteil das Menschen nicht extra Node/npm lokal installieren müssen um die Seite zu bearbeiten.
Package.json dient damit eher als informative Liste, was so benutzt wird.
Die seitenweite und Blogsuche funktionieren komplett clientseitig mit lunr.js. Dafür generiert Hugo zwei JSON-Dateien, einmal mit allen Blogposts und einmal mit allen Inhalten der Seite.
Diese JSON-Dateien werden auf Travis mit Node-Scripten (siehe /scripts/ci/*
) in Suchindexe geparst und serialisiert (siehe /scripts/lunr/*
) und wieder als JSON gespeichert.
Die serialisierten Suchindexe können im Browser direkt von lunr gelesen und verwendet werden, das spart die Indexierung 'on the fly' bei jedem Seitenaufruf.
Leider sind die Suchindexe sehr groß, was sich auf die Ladegeschwindigkeit der Seite auswirkt.
Es gibt die Möglichkeit Seiten explizit aus der Suche auszuschließen. Setze hierfür layout: none
im Frontmatter.
Es gibt auch die Möglichkeit extra Suchwörter als Tags auf einer Seite anzugeben. Setze hierfür Begriffe als Liste im Frontmatter:
search_keys:
- custom
- keyword
Der Buildprozess verläuft in mehreren Stufen:
- der Push wird von GitHub registriert und stößt einen Build bei Travis CI an
- hier wird die Seite mit Hugo gebaut
- zwei Nodescripte erstellen die Suchindexe (als .json) für die seitenweite und die Blogsuche
- (wegen dieser Scripte brauchen wir Travis, Hookay kann das nicht alleine)
- der Atom und RSS feed wird an die selben Stellen kopiert, auf der sie auf der alten Seite zu finden waren
- ist ein Travis-Build auf dem Master branch erfolgreich, pusht Travis die gebaute Seite zurück zu GitHub, aber auf den Release branch
- dieser Badge zeigt den Status des letzten Builds an
- ist der Badge rot ist schon was beim bauen der Seite schief gelaufen. Vermutlich was mit Hugo in den Templates, hier musst du debuggen!
- hat Travis auf den Release branch gepusht, sendet GitHub einen Webhook an Hookay
- Hookay klont den Release branch auf unseren Server und kopiert ihn an die richtige Stelle
- es kann sein, dass die Webhook-payload von GitHub sehr groß ist und Hookay dann einen Fehler wwirft. Das kannst du hier (sofern du die Rechte hast) nachsehen.
- Ist beim letzten senden eines Webhooks was schief gelaufen (Fehler 413) dann kannst du über Hookay die Seite manuell neu bauen. Die gebaute Seite liegt ja schon bei GitHub und muss nur kopiert werden.
Wenn alles geklappt hat, sind dein Änderungen jetzt online!