2022-11-21 13:24:44 +01:00
|
|
|
# Freifunk Franken Dokumentation
|
2022-11-17 22:38:34 +01:00
|
|
|
|
2022-11-21 13:24:44 +01:00
|
|
|
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.
|
|
|
|
|
|
|
|
### 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
|