Freifunk Franken Dokumentation

https://docs.freifunk-franken.de/

Orientierung

https://gohugo.io/getting-started/directory-structure/

• content
  • Hier liegen die Markdown Quellen für alle Seiten in der Dokumentation. Die Struktur wird auf der Webseite widergespiegelt.
  • Auf der Webseite wird auf jeder Seite im Footer der letzte Commit verlinkt.
• archetypes
  • Vorlagen für hugo new (siehe Neue Seite anlegen)
• layouts
  • Ordner für extra templates

Lokale Live Vorschau

Obwohl hugo ein Static Site Generator ist, kann das Ergebnis von gespeicherten Änderungen direkt im Browser überwacht werden. Dazu muss man den eingebauten HTTP Server starten und im Browser http://localhost:1313 öffnen:

hugo server

Um außerdem Seiten zu rendern, die als draft (Entwurf, siehe content/example und http://localhost:1313/example/) markiert sind, muss noch der -D/--buildDrafts Parameter angehängt werden:

hugo server --buildDrafts

Um Fehler beim editieren frühzeitig zu erkennen, eignen sich alle, oder ein Teil folgener Parameter:

hugo server --buildDrafts --printPathWarnings --disableFastRender --verbose --debug --ignoreCache

Änderungen erstellen

Seite bearbeiten

Dazu einfach die entsprechende Seite editieren und einen Pull-Request erstellen.

Neue Seite anlegen

Man kann hugo new nutzen um Vorlagen aus dem Ordner archetypes.

hugo new content/pfad/zur_neuen_seite.md
hugo new content/pfad/zur_neuen_seite/index.md

Der erste Absatz sollte eine kurze Zusammenfassung sein und mit <!--more--> (exakte Zeichenfolge, kein extra Leerzeichen verwenden!) vom Rest getrennt werden. Der Absatz kann so in den Übersichtsseiten als Vorschau verwendet werden.

Neues Kapitel anlegen

mkdir content/neues_kapitel
hugo new content/neues_kapitel/_index.md

Danach die _index.md bearbeiten und title: anpassen.

Wenn das Kapitel nicht klickbar sein soll, sondern nur zur Struktur dient, darf die Datei keinen weiteren Inhalt haben.

Wenn automatisch eine Liste mit den Seiten und deren Zusammenfassungen in einem Kapitel erstellt werden sollen, muss folgender Shortcode eingfügt werden:

{{< section >}}

Danach das title: Attribut in der Datei anpassen.

Änderungen vorschlagen

1. Pull Request

Die bevorzugte Variante Änderungen vorzuschlagen geht über Pull-Request.

Repository Fork

1. Repository Fork
2. git clone gitea@git.freifunk-franken.de:<user>/docs.git
3. git remote add upstream gitea@git.freifunk-franken.de:freifunk-franken/docs.git
4. git pull --rebase upstream master

Änderung erstellen

Jede Änderung sollte in einem eigenen branch passieren. Sonst ist es nicht möglich mehrere Änderungen gleichzeitig zu verwalten und vorzuschlagen.

1. git checkout -b meine_aenderung
2. Editieren
3. git commit -av
4. git push
5. URL in der Ausgabe folgen und Pull-Request öffnen

Änderungen korrigieren

Beim Sichten der Änderungen können Korrekturen verlangt oder nötig sein. Wenn die Änderung nur aus einem Commit besteht kann man folgendermaßen vorgehen:

1. git checkout meine_aenderung
2. Editieren
3. git commit --amend -av, oder git commit --amend -v <datei>
4. git push -f

Bei komplizierteren Änderungen über mehrere Commits wird git rebase benötigt.

Vorschau

Für Pull Requests wird automatisch eine Vorschau gerendert. Wenn die Seite erfolgreich generiert werden kann, erscheint hinter dem Commit und auf der Seite vom Pull Request ein grüner Haken. Dort werden Details zum Buildprozess hinterlegt und ein Link zur Vorschau:

2. Issue erstellen

Änderungen können auch über ein issue vorgeschlagen werden, falls die Arbeit mit git nicht möglich ist.