# 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`][hugo-new] (siehe [Neue Seite anlegen](#neue-seite-anlegen))
- `layouts`
	- Ordner für extra `templates`

## Lokale Live Vorschau

Obwohl [hugo] ein [Static Site Generator][SSG] 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](http://localhost:1313) öffnen:

```sh
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:

```sh
hugo server --buildDrafts
```

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

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

## Änderungen erstellen

### Seite bearbeiten

Dazu einfach die entsprechende Seite editieren und einen [Pull-Request](#1-pull-request) erstellen.

### Neue Seite anlegen

Man kann [`hugo new`][hugo-new] nutzen um Vorlagen aus dem Ordner
[`archetypes`][archetypes].

```sh
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

```sh
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][shortcode] eingfügt
werden:

```markdown
{{< 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:

![Screenshot Vorschau Commit](preview_commit.png)
![Screenshot Vorschau Pull Request](preview_pr.png)

### 2. Issue erstellen

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

[hugo]: https://gohugo.io
[SSG]: https://en.wikipedia.org/wiki/Static_site_generator
[issue]: https://git.freifunk-franken.de/freifunk-franken/docs/issues/new
[hugo-new]: https://gohugo.io/commands/hugo_new/
[archetypes]: https://gohugo.io/content-management/archetypes/
[shortcode]: https://gohugo.io/content-management/shortcodes