Die Neo-Dokumentation und -Homepage mit MkDocs.
Go to file
Domenic Kipphan 4519da7bc8 Rechtschreibkorrektur 2021-07-20 17:23:10 +02:00
docs Rechtschreibkorrektur 2021-07-20 17:23:10 +02:00
overrides Korrektur Link sowie Tippfehler 2021-05-12 12:29:50 +02:00
snippets Glossar in die FAQ eingefügt, Beschreibung der Notation von Tastenkombinationen 2021-02-08 22:01:46 +01:00
.gitignore ignore venv 2021-01-13 04:57:52 +01:00
README.md Aktualisierung der README 2021-07-07 00:54:11 +02:00
guix.scm Verwende spezifischen commit von guix 2021-05-12 07:41:01 +02:00
mkdocs.yml Entwicklerseite zu NeoVars sowie einige Erwähnungen entfernt; Formatierung 2021-07-07 02:10:18 +02:00
requirements.txt Kompatible Abhängigkeiten hinzugefügt 2021-05-12 02:37:42 +02:00

README.md

Neo ergonomisch optimiert
Dokumentation

Änderungen direkt über Gitea

Auf den Dokumentationsseiten befindet sich ein Knopf, über den die Seite im Gitea-Editor geändert werden kann. Die Dokumentation wird automatisch neu gebaut, wenn Änderungen im master-Branch eingehen und kann unter https://neo-layout.org/ eingesehen werden.

Selber Bauen

Anforderungen

  • MkDocs Statischer Seitengenerator
  • MkDocs-Material Material-Theme für MkDocs
  • Git in irgendeiner Form

Herunterladen

Das Dokumentations-Repository herunterladen und entpacken oder mittels Befehl klonen:

git clone https://git.neo-layout.org/neo/dokumentation.git

Das Produktivsystem verwendet zur Zeit Version 6.1.4 von mkdocs-material. Eine kompatible Testumgebung kann man mit

python -m venv venv
./venv/bin/activate
pip install -r requirements.txt

aufsetzen.

Bauen

Den lokalen MkDocs Server im Dokumentations-Repository mit mkdocs serve starten. Die Dokumentation wird nun auf http://localhost:8000 angezeigt und bei Änderungen automatisch aktualisiert.

Mittels mkdocs build kann die gesamte Dokumentation statisch generiert werden. Die entstandenen Dateien finden sich im Verzeichnis site.

Struktur

.
├─ docs/                   # Dokumentationsstexte im Markdownformat
│  ├─ Einrichtung/         # Neo einrichten
│  ├─ Benutzerhandbuch/    # Einzelne Seiten zum Benutzerhandbuch
│  ├─ Beitragen/           # Kontakt, Mitmachen, Mitentwickeln
│  ├─ Download/            # Markdown für Download und Installation
│  ├─ .../                 # und andere Bereiche der Dokumentation / des Benutzerhandbuchs
│  └─ index.md             # Setzen des Startseitentemplates
├─ overrides/              # Themaanpassungen nach Materialvorgabe
│  ├─ assets/
│  │  ├─ images/           # Icons, Logos und Bilder für die Startseite
│  │  └─ stylesheets/      # Zusätzliche Stilanpassungen
│  ├─ overrides/
│  │  └─ home.html         # Startseitentemplate
│  ├─ partials/
│  │  ├─ footer.html       # Anpassung des Footers
│  │  ├─ tabs-item.html    # Anpassung der Tabbar um Tabs mit Einzelseiten zu erlauben
│  │  └─ header.html       # Anpassung des Headers
│  └─ main.html            # Anpassung des Haupttemplates
├─ mkdocs.yml              # MkDocs Konfiguration
└─ README.md