README.md: add basic build contribution instructions
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful

This commit is contained in:
Johannes Kimmel 2022-11-21 13:24:44 +01:00
parent 7fd6f3698d
commit d9898446a8

134
README.md
View File

@ -1,3 +1,133 @@
# docs
# Freifunk Franken Dokumentation
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.
### 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