forked from freifunk-franken/docs
README.md: add basic build contribution instructions
This commit is contained in:
parent
7fd6f3698d
commit
d9898446a8
134
README.md
134
README.md
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue