Was ist das hier?

Die Website des RUB-Makerspace. Online-Ansicht derzeit unter [Einfügen] - später unter https://makerspace.rub.de

Inhalt für die Website schreiben - Ab hier kann einiges veraltet sein!

Es gibt verschiedene Wege zum Ziel:

• Einfachster Weg für schnelle Änderungen: "Edit-Button" oben rechts auf allen Unter-Websites unter https://makerspace.io.noc.ruhr-uni-bochum.de/homepage/ nutzen

• Für mehr Funktionalität: Drückt in Gitlab einfach mal auf "Web-IDE". Ihr solltet dann eine deutlich mächtigere Version des einfachen Standard-Texteditors sehen, in dem zum einen alle Dateien zu sehen sind und in dem zum anderen zum Beispiel auch Dateien verschoben, hochgeladen, umbenannt, etc. werden können (IDE = "integrated development environment").

  • Hier ein Direktlink zur IDE-Ansicht unseres /docs-Ordners
  • Ganz links hat die IDE drei Buttons, die nacheinander von oben bis unten einen sinnvollen Workflow ergeben: Editieren, dann bei Bedarf Review (Vergleich vorher-nachher), dann Commit (die bearbeiteten Dokumente zurück vom für die Bearbeitung erstellten "Branch" / Zweig des Datenbestandes nach Gitlab in den Haupt-Datenbestand übertragen)
  • Bitte ggf. bei Commits "Commit to main branch" wählen

• Das komplette Gitlab-Repository unserer Projekt-Seite kann man natürlich auch lokal auf seinen Rechner spiegeln und von dort aus mit Tools nach eigener Wahl bearbeiten. Siehe "An der Website hacken")

Weitere Infos zum Inhalt und zu Markdown

• Im Wesentlichen besteht der Inhalt der Website aus allem, was unter /docs liegt. Das sind hauptsächlich Text-Dateien mit der Datei-Endung .md (das sind einfach nur umbenannte .txt-Dateien) und Fotos/Videos im Unterordner docs/medien.

• Jede Unter-Website hat eine eigene *.md-Datei. Der Name dieser Datei ergibt den letzten Teil der URL (aus "designlabor.md" wird im Moment "https://makerspace.io.noc.ruhr-uni-bochum.de/homepage/designlabor/" bzw. in Zukunft nach Live-Schaltung der Website dann wohl "https://makerspace.rub.de/designlabor")

• Die Website wird in Markdown geschrieben, weil das ein guter Kompromiss ist, um Inhalte so zu schreiben, dass sie (technisch) direkt im Internet veröffentlicht werden können - ohne dabei gezwungen zu sein, HTML zu lernen oder aufwändigere Werkzeuge (Sharepoint und Co) verwenden zu müssen.

• Die Dokumentation von mkdocs-material ist super und beschreibt/zeigt viele auf unserer Website eingesetzte Funktionen gut. Auch die unter "An der Website hacken" genannten Plugins oder andere Plugins kann man sich mal anschauen (nicht unbedingt aus technischer Sicht, sondern um zu verstehen, was sie einem beim Schreiben / Strukturieren von Inhalt für Möglichkeiten geben)

• Für gestalterische Eingriffe braucht man unter Umständen ein wenig (Grundlagen-)HTML und CSS. Aber man kann sich ja auch erstmal auf den Content konzentrieren. :-)

Ordnerstruktur

Für den Alltag wichtig

/docs = Quelldateien der Website. Wichtigster Arbeits-Ordner für den Alltag

/docs/medien = Fotos und Videos

/docs/news und /docs/news-entwuerfe = Siehe https://makerspace.io.noc.ruhr-uni-bochum.de/homepage/news-entwuerfe/news-vorlage/

/slides = Ordner für alle Foliensätze (s. https://makerspace.io.noc.ruhr-uni-bochum.de/homepage/slides/)

mkdocs.yml = Konfigurationsdatei für Mkdocs. Hier werden allgemeine Optionen für die Website festgelegt, Plugins geladen und - wichtig für den Alltag - die Navigation der Website konfiguriert.

Weitere Unterordner unter /docs

/docs/en = Für zukünftige englische Version der Website

/docs/javascripts = Für technische Dinge erforderlicher Javascript-Code. Für den Alltag unwichtig

/docs/stylesheets = CSS für gestalterische Anpassungen. Für den Alltag unwichtig.

/docs/overrides = Overrides an mkdocs-material. Für den Alltag unwichtig

/docs/sicherheit = Tests zum Thema Sicherheit. Für den Alltag unwichtig

Weitere Ordner

/tables = Test-Ordner für Experimente mit Tabellen. Für den Alltag unwichtig.

/public = HTML-Version, gehostet über GitLab Pages. Hier muss man eigentlich nie manuell dran und der Ordner wird beim nächsten Build sowieso überschrieben.

Einzelne Dateien

.gitlab-ci.yml = Konfigurationsdatei für unsere Gitlab-CI. CI = Continuous Integration = Tools, mit denen (zum Beispiel nach Änderungen von Dateien, nach Zeit, usw.) automatisierte Prozesse losgetreten werden können. Wir nutzen das, um die Online-Version unserer Website automatisch zu aktualisieren, nachdem wir Quelldateien bearbeiten. Mehr dazu s.u.

.gitignore = Git-Konfiguration. Für den Alltag unwichtig

LICENSE.md = Lizenz-Informationen

README.md = Diese Datei

An der Website hacken

• Git installieren. Empfehlung: Einfach Github Desktop verwenden und für die Verwendung mit unserem Gitlab-Projekt konfigurieren.
• Python 3 installieren: https://www.python.org/downloads/ (Empfehlung für Menschen mit Mac: Erst Homebrew - https://brew.sh/ - installieren, dann darüber Python)
• Erforderliche Software rund um mkdocs installieren:
  • https://www.mkdocs.org/
  • https://squidfunk.github.io/mkdocs-material/
  • Folgende Mkdocs-Plugins installieren:
    • table-reader: https://timvink.github.io/mkdocs-table-reader-plugin/
    • footermatter: https://github.com/sondregronas/mkdocs-footermatter/
    • glightbox: https://blueswen.github.io/mkdocs-glightbox/
    • mkdocs-video: https://github.com/soulless-viewer/mkdocs-video
    • rss: https://guts.github.io/mkdocs-rss-plugin/
    • page-to-pdf: https://pypi.org/project/mkdocs-page-pdf/
    • git-revision-date-localized: https://timvink.github.io/mkdocs-git-revision-date-localized-plugin/index.html
    • i18n: https://github.com/ultrabug/mkdocs-static-i18n
• Falls noch nicht vorhanden: Vernünftigen Text-Editor installieren - https://www.sublimetext.com/ / https://code.visualstudio.com/ (oder besser: https://vscodium.com/ ) / https://kate-editor.org/ u.v.m. ...

Nach Runterladen / Fetch / Pull via Git, kann man nun in der Kommandozeile im runtergeladenen Ordner mit dem Befehl "mkdocs serve" lokal an der Website arbeiten. Jede Änderung an *.md-Dateien wird dann live im Browser angezeigt.

Per "mkdocs build" wird die Seite neu gebaut. Bevor man nach dem Bauen der Seite zurück nach Git committed, muss der (alte) Unterordner /public gelöscht werden und der (neue) von mkdocs für den Build neu erzeugte Ordner "site" in "public" umbenannt werden.

Automatisierung des Build-Prozesses

Der Plan ist, dass nach einer Datei-Änderung die Online-Version der Website automatisch neu gebaut wird ("mkdocs build") und als Gitlab-Page (eine solche ist unsere Website) veröffentlicht wird. Letzteres klappt schon (dafür ist die o.g. .gitlab-ci.yml-Datei da). Der automatisierte build-Prozess ist aber noch nicht fertig. Einiges dafür schon vorbereitet, aber es fehlt noch ein fertig eingerichteter Computer/Server, auf dem mkdocs, mkdocs-material und alle o.g. Plugins installiert sind und der unserem Gitlab-Projekt als "Runner" zugänglich ist. Bis das soweit ist, muss die Seite manuell neu gebaut werden (s. "An der Website hacken").