Die eigene Website mit Material for MkDocs bei Codeberg Pages

Codeberg Pages bietet eine sehr komfortable und einfache Möglichkeit eine eigene statische Website kostenlos zu hosten. Die Erreichbarkeit über die eigenen Domains wird dabei genauso angeboten, wie ein aktuelles Let's Encrypt Zertifikat.

Die Ordner und Dateien werden in zwei unterschiedlichen Git Repositories verwaltet, einem öffentlichen für die Website und einem privaten für die Quelldateien. Es wird dafür die Git-Funktion Submodules verwendet.

Meine neue Website wurde mit Material for MkDocs erstellt und wird auf Codeberg bereitgestellt.

1. Das Ziel

Die Webseite soll über Codeberg Pages über die eigene Domain meine-domain.de erreichbar sein.

Alle Quelldateien (= Markdown-Dateien) sollen in einem eigenen Git Repository verwaltet werden. Dieses Repository kann, muss aber nicht bei Codeberg abgelegt werden. Es kann auf jedem anderen Git Server verwaltet werden.

In diesem Beispiel wird das Repository mit den Quelldateien mkdocs genannt (= Hauptrepository).

In einem zweiten Repository sollen alle Webseiten-Dateien, also die statischen html-Dateien, verwaltet werden. Der Übertrag auf das Codeberg Pages Repository soll mit git push erfolgen.

In diesem Beispiel wird das Repository mit den statischen Webseitendaten site genannt. (= Sub-Repository)

Note

Bei der Verwendung von Material for MkDocs können alle Dateien in den Ordner außer site bearbeitet werden.

Die Daten im Ordner site werden NICHT bearbeitet. Diese werden automatisch erstellt und sind die fertige Website, die auf den Webserver geladen werden.

2. Material for MkDocs installieren

Es wird ein neuer Ordner mit dem Namen mkdocs angelegt. Das ist der Hauptordner und enthält alle Ordner und Dateien. In diesem Ordner werden alle Ordner und Dateien von Material for MkDocs automatisch angelegt.

mkdir mkdocs

Der Befehl zum Erstellen der ersten Seite lt. mkdocs new . ¹

cd mkdocs

mkdocs new .

Die Ordnerstruktur sieht wie folgt aus:

Ordnerstruktur mkdocs ohne Git

mkdocs
|
|- docs
|
|- - blog
|
|- - index.md
|
|- - assets 
|
|- - posts
|
|- - stylesheets
|
|- material
|
|- mkdocs.yml

Testet man die Seite nach der Anpassung der mkdocs.yml mit dem Befehl mkdocs serve oder mkdocs serve --livereload werden weitere Dateien automatisch angelegt.

site-Ordner wird erst später erstellt

Der Befehl (mkdocs build) zum Erstellen der finalen Website wird erst später ausgeführt. Dafür wird das zweite Repository site als Submodule benötigt.

Wurde der Ordner site bereits angelegt, kann dieser normalerweise problemlos gelöscht werden. Der Ordner und dessen Inhalt wird durch Material for MkDocs automatisch wieder angelegt.

3. Zwei Git Repositories

Für das Projekt werden zwei neue Git Repositories benötigt.

Name	Sichtbarkeit	Inhalt	Git	Wo abspeichern
`mkdocs.git`	privat	Quelldateien	Hauptrepository	Codeberg, eigener Git Server, etc.
`site.git`	öffentlich	fertige Website	Submodule	Codeberg

mkdocs.git = alle Ordner und Dateien außer site
site.git = nur der Ordner site

git submodule

Für die einfachere Verwaltung der beiden Git Repositories wird auf git submodule zurückgegriffen. Da mkdocs build die statischen html-Dateien automatisch in einen eigenen Ordner site ablegt, machen wir uns das zunutze.

Es wird der Ordner site aus dem Hauptrepository mkdocs herausgelöst und nur der Inhalt des site-Ordners wird zu Codeberg übertragen.

Git Repository mkdocs.git initialisieren - Privat

Das Repository mkdocs ist über die Weboberfläche bei Codeberg oder auf einem anderen Git Server neu zu erstellen.

Auf dem lokalen Client ist das Git Repository im Hauptordner mkdocs, dort wo sich auch die mkdocs.yml befindet, zu initialisieren.

Git-Repository initialisieren

git init
git checkout -b main
git add *
git commit -m "first commit"
git remote add origin ssh://git@codeberg.org/.../mkdocs.git
git push -u origin main

Im Repository mkdocs.git ist eine .gitignore zu erstellen. Der Ordner site mit den fertigen Dateien für unsere Website, soll nicht mit verwaltet werden. Dieser Ordner soll ausschließlich im zweiten Repository site.git eingefügt werden.

nano .gitignore

Der Inhalt der .gitignore muss mindestens den Ordner site beinhalten. Das ist das zukünftige Submodule.
Der Ordner .cache/plugin/social enthält die Vorschaubilder, deren Verwaltung durch Git optional ist und wird deshalb hier ausgeschlossen.

# Inhalt .gitignore
site/

.cache/plugin/social

Die Ordnerstruktur sieht danach wie folgt aus

Ordnerstruktur mkdocs.git

mkdocs
|
|- .git
|
|- docs
|
|- - blog
|
|- - index.md
|
|- - assets 
|
|- - posts
|
|- - stylesheets
|
|- material
|
|- .gitignore
|
|- mkdocs.yml

.git = Der Ordner enthält alle Informationen zum Git-Repository.
.gitignore = Dort werden Ordner und Dateien festgelegt, die nicht durch Git in diesem Repository verwaltet werden sollen, also der Ordner site.

Gib mir gerne einen Kaffee ☕ aus 😀

Gib mir gerne einen Kaffee ☕ aus !

Wenn dir meine Beiträge gefallen und geholfen haben, dann kannst du mir gerne einen Kaffee ☕️ ausgeben.

•

Bitcoin Address:

bc1qfuz93hw2fhdvfuxf6mlxlk8zdadvnktppkzqzj

Weitere Möglichkeiten mich zu unterstützen findest du 👉 hier

Submodul site.git anlegen - Öffentlich

Das zweite Repository site.git wird im ersten Git Repository mkdocs.git als Submodule angelegt. Dieses Repository enthält nur den Ordner site.

Das Repository site.git ist wieder über die Weboberfläche von Codeberg anzulegen, unter Beachtung der Vorgaben für Codeberg Pages. (👉 https://codeberg.page/ )

Der Hauptbranch muss pages benannt sein.
Das Repository muss öffentlich sichtbar sein.

In diesem Beispiel wird auch das Git Repository selbst pages benannt.

Für das Anlegen des Submodule, muss man sich Hauptordner befinden, dort wo die mkdocs.yml abgespeichert ist.

Ordnerstruktur mkdocs.git

mkdocs
|
|- .git
|
|- docs
|
|- - blog
|
|- - index.md
|
|- - assets 
|
|- - posts
|
|- - stylesheets
|
|- material
|
|- .gitignore
|
|- mkdocs.yml

Das Submodule wird mit den beiden Befehlen erstellt.

Es wird im Ordner mkdocs begonnen:

git submodule add ssh://git@codeberg.org/.../site.git site

cd site

# Der Branche "pages" wird erstellt
git checkout -b pages

Das Signieren der Commits mit dem eigenen GnuPG-Schlüssel wird empfohlen, um die Integrität zu gewährleisten. Das wird durch das grüne Schloss Icon angezeigt.

Ein Git Commit - es wird der Hashwert und ein grünes Schloss Icon angezeigt — Grünes Schloss Icon

# Signieren für dieses Repository abschalten (optional)
git config commit.gpgsign false

Fehlermeldung .gitignore

Es kann sein, dass diese Fehlermeldung auftaucht:

Die folgenden Pfade werden durch eine Ihrer ".gitignore" Dateien ignoriert:
site 
Hinweis: Verwenden Sie -f, wenn Sie diese wirklich hinzufügen möchten.
Hinweis: Disable this message with "git config set advice.addIgnoredFile false"

In der .gitignore im Hauptverzeichnis mkdocs ist der Eintrag für site/ zu kommentieren #site/.

nano .gitignore

Nachdem das Submodule angelegt wurde, ist die Zeile wieder in die .gitignore einzufügen

Der Submodule-Befehl erstellt einen neuen Ordner site den wir später für die fertige MkDocs-Website benötigen.

Die Ordnerstruktur von mkdocs sieht wie folgt aus:

Ordnerstruktur site.git

mkdocs
|
|- .git
|
|- docs
|
|- - blog
|
|- - index.md
|
|- - assets 
|
|- - posts
|
|- - stylesheets
|
|- material
|
|- mkdocs.yml
|
|- site

Wo ist das Submodule zu finden?

Die Git-Informationen des Submoduls sind in einem Unterordner von .git zu finden:

.git
|
| - modules
| - - site

Im Ordner site ist die bekannte Git-Ordner- und Dateistruktur zu finden.

mkdocs
|
| - site
| - - .git

Die Datei .git enthält lediglich einen Verweis auf das Git-Verzeichnis gitdir: ../.git/modules/site. Das ist erforderlich, dass Git-Client wie Fork, die Informationen zum Repository finden.

In den neuen Ordner site wechseln.

cd site

Eine neue .gitignore-Datei ist anzulegen, damit alles was nicht zur Website gehört auf dem eigenen Client verbleibt.

touch .gitignore

Der Inhalt der .gitignore kann beispielhaft wie folgt aussehen:

# Please see https://github.com/github/gitignore for file templates

# Der Schrägstrich am Ende einiger Zeilen signalisiert, dass es sich um einen Ordner handelt und alles
# darin rekursiv ignoriert wird. z.B. bin/
# Das Sternchen dient seiner üblichen Funktion als Platzhalter (Wildcard).

*.log
.DS_Store
.git
.gitattributes
.gitignore

4. Codeberg Pages und die eigene Domain

Wer möchte, kann Codeberg Pages auch über die eigene Domain erreichbar machen. Dazu ist eine Datei mit dem Namen .domains anzulegen und zu befüllen.

nano .domains

In die Datei sind die Domains einzutragen, über die die Seite erreichbar sein soll.

meine-domain.de
www.meine-domain.de

Das Repository site kann bereits jetzt übertragen werden, jedoch ist das wenig spannend. Es befindet sich höchstens die .gitignore und die .domains darin.

Vor dem ersten Übertrag in das Submodule site lassen wir MkDocs alle Dateien für die fertige Website erstellen.

# Prüfen
mkdocs serve

# Website erstellen
mkdocs build

Mit dem Befehl mkdocs build werden alle notwendigen Dateien für die Website in den Ordner site also unserem Submodule übertragen.

Der gesamte Inhalt des Ordners site soll zu Codeberg Pages übertragen werden. Dafür verwenden wir die bekannten Git Befehle von weiter oben.

❗️ Der Hauptbranche muss pages benannt sein. (git checkout -b pages)

Der Ablauf zum Hochladen der fertigen Website zu Codeberg Pages hat folgende Schritte

# Wechsel in den Ordner site, unserem Submodule
cd site

# Hinzufügen aller Dateien zum Commit
git add *

# Beschreibung des Commits
git commit -m "first website release"

# Übertragen aller Dateien auf Codeberg Pages
git push -u origin pages

Note

Für jeden Übertrag in des Git Submodule wird ein neuer Commit angelegt. Wer das nicht möchte, kann auch den vorherigen Commit ergänzen (amend).

Damit werden die Dateien für die Website zu Codeberg Pages geladen. Die Quelldateien von MkDocs verbleiben auf dem eigenen Client, also alles was im Repository ist mkdocs.

Die Seite ist sofort über die Adresse erreichbar

# Codeberg - allgemeiner Aufruf
https://USERNAME.codeberg.page/repository

# Für unser Beispiel bedeutet das
https://USERNAME.codeberg.page/site

https://sst.codeberg.page/sst/

Die Seite bekommt automatisch ein Zertifikat von Let's Encrypt. Irgendwelche Einstellungen oder Anpassungen dafür sind nicht notwendig.

Submodule auf einem weiteren Client einrichten

Die beiden Git-Repositories lassen sich auch auf weiteren Client einrichten.

Das Haupt-Repository, also das mkdocs.git kann einfach auf den neuen Client geklont werden. Es werden alle Dateien, damit .gitignore, in einen beliebigen Ordner auf der eigenen Festplatte vom Git-Server heruntergeladen.

Das Submodule kann dagegen nicht nach der obigen Anleitung erstellt werden. Das dort beschriebene Vorgehen erzeugt einen Fehler.

Fehlermeldung

git submodule add ssh://git@codeberg.org/.../site.git site
The following paths are ignored by one of your .gitignore files:
site
hint: Use -f if you really want to add them.
hint: Disable this message with "git config set advice.addIgnoredFile false"
❯ git submodule add ssh://git@codeberg.org/.../site.git site
fatal: 'site' already exists and is not a valid git repo

Die Lösung ist:

der Ordner site wird auf dem neuen Client gelöscht
Im Hauptordner mkdocs wird der Befehl zum Anlegen des Submodules ausgeführt
Die Anmeldedaten für das Submodule-Repository sind einzugeben
Das Submodule mit allen Dateien wird heruntergeladen

Submodule anlegen und Dateien herunterladen

❯ sudo rm -r site
❯ git submodule add ssh://git@codeberg.org/.../site.git site
Cloning into '/home/<benutzer>/git/websites/site'...
warning: redirecting to https://git@codeberg.org/.../site.git/
remote: Enumerating objects: 1142, done.
remote: Counting objects: 100% (1142/1142), done.
remote: Compressing objects: 100% (849/849), done.
remote: Total 1142 (delta 182), reused 1142 (delta 182), pack-reused 0
Receiving objects: 100% (1142/1142), 68.62 MiB | 636.00 KiB/s, done.
Resolving deltas: 100% (182/182), done.
The following paths are ignored by one of your .gitignore files:
site
hint: Use -f if you really want to add them.
hint: Disable this message with "git config set advice.addIgnoredFile false"
fatal: Failed to add submodule 'site'

Es werden dabei alle notwendigen Dateien im Verzeichnis ~/.git/modules automatisch angelegt.

DNS-Einstellungen bei Strato

Meine Domain wird von Strato verwaltet. Dort sind in der Domainverwaltung die DNS-Einstellungen entsprechend der Codeberg-Vorgaben zu erstellen.

👉 https://docs.codeberg.org/codeberg-pages/using-custom-domain/

Die IP-Adressen sind im Abschnitt "Option 3: A/AAAA record" zu finden

Wurde die .domains-Datei erstellt, ist die Seite über die eigene Domain erreichbar:

https://strobelstefan.de

INWX

INWS DNS-Einstellungen — Einstellungen: INWX DNS

5. Sonstiges

Die Quelldateien müssen nicht in einem eigenen Git Repository mkdocs verwaltet werden. Sie können auch einfach in einer normalen Ordner- und Dateistruktur auf dem eigenen Client abgelegt werden.

Wer das möchte, benötigt nur ein Git Repository für den Ordner site und kann somit auf git submodule verzichten.

Im nächsten Beitrag wird gezeigt, wie sich jeder Git Commit mit einem GPG-Schlüssel signieren lässt, um die Echtheit der Dateien und Informationen nachzuweisen und zu gewährleisten.

👉 Git Commits mit GPG-Schlüssel signieren

YubiKey Themenseite

Hier geht es zur 👉 YubiKey Themenseite, dort findest du noch mehr Beiträge rund um den YubiKey.

Die Manuals zum Einrichten und Konfigurieren von YubiKey und Nitrokey sind umgezogen umgezogen.

6. Codeberg unterstützen

Codeberg und Codeberg Pages ist und bleibt kostenlos. Es wird über Mitgliedern und Spenden finanziert.

🇩🇪 Satzung
🇬🇧 Bylaws

Wenn ihr den Dienst nutzt oder das Projekt toll findet, überlegt euch mit ein paar Euro Codeberg zu unterstützen. Kosten für eure Website habt ihr mit Codeberg Pages bereits eingespart.

👉 Mitglied werden https://join.codeberg.org/
👉 Spenden https://docs.codeberg.org/improving-codeberg/#donate-to-codeberg

7. Grafische Darstellung der eigenen Website

Eine nette Funktion ist bei der Verwendung von Markdown-Dateien, dass sich die Verbindungen und Abhängigkeiten zwischen den einzelnen Dateien sehr schön mit der Erweiterung Foam in VSCodium darstellen lassen. (Das ist Vergleichbar mit dem Graph view in Obsidian.)

FOAM - grafische Darstellung aller Verbindungen

Gib mir gerne einen Kaffee ☕ aus 😀

Gib mir gerne einen Kaffee ☕ aus !

Wenn dir meine Beiträge gefallen und geholfen haben, dann kannst du mir gerne einen Kaffee ☕️ ausgeben.

•

Bitcoin Address:

bc1qfuz93hw2fhdvfuxf6mlxlk8zdadvnktppkzqzj

Weitere Möglichkeiten mich zu unterstützen findest du 👉 hier

Follow Me

Mastodon • Mastodon RSS • codeberg.org/sst • RSS

Source

Foto von Hal Gatewood auf Unsplash

Creating your site ↩