Schnelleinstieg
In wenigen Schritten zu eigenen OER
Zusammenfassung
Hier ist aufgeschrieben, wie die Quarto-Templates praktisch genutzt werden können.
Die erzeugten Quarto-HTML-Dokumente sind flexibel einsetzbar. Sie können lokal genutzt, in bestehende Systeme integriert oder online veröffentlicht werden. Eine öffentliche Bereitstellung wird durch die Templates erleichtert, ist jedoch keine Voraussetzung für ihre Nutzung.
OER, FAIR, Templates, Quarto
Diese Seite ist noch im Aufbau. Inhalte und Struktur werden derzeit erarbeitet und werden sich ändern.
Vom Template zum Quarto-Dokument in vier Schritten
In diesem Schnelleinstieg lernen Sie Schritt für Schritt, wie Sie aus einem Template ein lokales Quarto-Projekt erstellen und rendern. Anschließend nehmen Sie eine kleine Änderung vor, um den grundlegenden Arbeitsablauf kennenzulernen.
Eine Veröffentlichung im Internet oder Vorkenntnisse zu Git und Git-Repositories sind dafür nicht erforderlich.
Am Ende haben Sie ein funktionierendes Projektverzeichnis und die HTML-Seiten auf Ihrem Rechner, die Sie anschließend direkt nutzen können.
Voraussetzungen
✅ Quarto: Für die Nutzung der Templates muss Quarto auf dem Rechner installiert sein (Version >=1.8.0). Einen guten Einstieg bietet das Get Started-Tutorial auf der Website des Projekts.
✅ Entwicklungsumgebung: Die NFDI4Objects OER-Templates wurden mit VSCodium als Entwicklungsumgebung und der Quarto-Erweiterung entwickelt. Weitere Entwicklunsumgebungen sind der Quarto-Dokumentation zu entnehmen.
Screenshots und Anleitung beziehen sich im folgenden auf VSCodium mit Quarto-Erweiterung.
Prüfen Sie die Version und die Installation von Quarto, indem Sie in VSCodium ein Terminalfenster öffnen (Menü - Terminal - Neues Terminal), auf der Konsole unten im Programmfenster: quarto --version eintippen und mit EnterEnter bestätigen.
Wenn eine Versionsnummer angezeigt wird, ist Quarto verfügbar.
Schritt 1: Lokales Projektverzeichnis anlegen und sinnvoll benennen
Legen Sie zuerst ein neues, leeres Verzeichnis auf Ihrem Rechner für Ihr Projekt an. Wählen Sie den Namen bewusst, weil er als Projektname dient und sich in vielen Fällen auch in Dateinamen wiederfindet. Verwenden Sie einen kurzen, sprechenden Namen ohne Leer- und Sonderzeichen.
Beispiele für geeignete Verzeichnisnamen:
/oer-templates-test//skript-template-demo//modul03_datenbanken/
Wenn Sie das Verzeichnis im Dateimanager angelegt haben, öffnen Sie das Verzeichnis innerhalb von VSCodium (Menü - File - Open Folder). Anschließend öffnen sie dort ein Terminalfenster.
Schritt 2: Template in das Projektverzeichnis übernehmen
Sie können ein Template auf zwei Arten in ein lokales Projekt überführen. Wählen Sie die Variante, die für Sie am einfachsten ist:
Mit
quarto use templatedas Template direkt in das Projekt-Verzeichnis laden und loslegen.Ein Zip-Datei herunterladen, lokal im Projekt-Verzeichnis entpacken, aufräumen und loslegen.
Wenn Sie Templates wiederholt nutzen möchten, ist diese Variante meist am angenehmsten. Sie führen dabei einen Quarto-Befehl aus, der ein neues Projektverzeichnis aus dem Template erstellt.
Wechseln Sie in ein Verzeichnis, in dem das neue Projekt entstehen soll und führen Sie dann quarto use template <Platzhalter> aus.
Für die OER-Templates von NFDI4Objects ergibt sich mit der Syntax:
Übungs-Template:
quarto use template nfdi4objects/oer-template-uebungSkript-Template:
quarto use template nfdi4objects/oer-template-skript
Beantworten Sie nun die Fragen im Terminal:
Do you trust the authors of this template?yesCreate a subdirectory for template?no
Ergebnis
Schließlich werden die Dateien des Templates im Ordner installiert. Die .qmd-Datei übernimmt im Dateinamen automatisch den Namen des Projektverzeichnisses. Sie können die .qmd-Datei aber später beliebig umbenennen.
quarto use templateÖffnen Sie die Seite des Template-Repositories im Browser:
- Übungs-Template: https://github.com/nfdi4objects/oer-template-uebung
- Skript-Template: https://github.com/nfdi4objects/oer-template-skript
Laden Sie dort das Repository als ZIP-Datei herunter und entpacken Sie das Archiv.
Achten Sie darauf, dass die Dateien des Templates direkt in Ihrem Projektverzeichnis liegen. Häufig entsteht beim Entpacken ein zusätzlicher Ordner. In diesem Fall verschieben Sie die Inhalte aus diesem Ordner in Ihr Projektverzeichnis.
Am Ende dieses Schritts sollte Ihr Projektverzeichnis mehrere Dateien und Unterverzeichnisse enthalten.
Ergebnis
Im Verzeichnis aus dem ZIP-Archiv liegen alle Daten aus dem GitHub-Repository des Templates. Den Ordner .github sollten Sie löschen. Die .qmd-Datei heißt template.qmd. Sie können die .qmd-Dateien aber später beliebig umbenennen.
Schritt 3: Projekt lokal rendern
Rendern bedeutet: Quarto erzeugt aus der .qmd-Datei eine HTML-Ausgabe. Führen Sie im Terminal des Projektverzeichnis’ folgenden Befehl aus: quarto render
Quarto verarbeitet nun die Dateien und erzeugt ein HTML-Dokument.
Nach dem Rendern finden Sie das Ergebnis im Ordner _site.
_siteSchritt 4: Ergebnis lokal öffnen
Öffnen Sie die gerenderte Startseite index.html im Browser. Sie können die Datei im Dateimanager per Doppelklick öffnen oder den Pfad direkt im Browser öffnen.
Erste sichtbare Änderung vornehmen
Nehmen Sie kleine, gut sichtbare Änderungen vor, um zu verstehen, wie Quarto funktioniert. Geeignet sind zum Beispiel der Titel und der Untertitel der Website.
Öffnen Sie dazu die .qmd-Datei in VSCodium. Am Anfang der .qmd-Datei stehen zwei Schlüssel: title und subtitle. Hier das Beispiel aus dem Übungs-Template:
---
title: "OER-Übung"
subtitle: "Untertitel der OER-Übung"Ändern Sie den Wert des Titels und des Untertitels. Speichern Sie anschließend die Datei.
Rendern Sie das Projekt erneut: quarto render
Öffnen Sie die Seite im Browser noch einmal oder laden Sie sie neu. Der geänderte Titel und Untertitel sollten nun angezeigt werden. Damit ist bestätigt, dass Ihr lokaler Workflow funktioniert und Änderungen zuverlässig in der Ausgabe ankommen.
Mit quarto render lassen Sie Quarto die Ausgabedateien vollständig neu erzeugen. Das entspricht einem „finalen Durchlauf“ des Projekts auf Ihrem Rechner. Dabei werden alle Dateien und Einstellungen ausgewertet, auch Änderungen an Konfigurationsdateien wie der _quarto.yml.
quarto preview zeigt Ihr Dokument hingegen in einer laufenden Vorschau im Browser an. Sobald Sie eine .qmd-Datei speichern, wird die Anzeige automatisch aktualisiert. Diese Vorschau eignet sich besonders gut, wenn Sie am Text oder an anderen Inhalten arbeiten.
Für Änderungen an der Projektstruktur oder an Konfigurationsdateien sollten Sie jedoch immer quarto render verwenden.
Zuweilen behält der Browser die Daten im Cache und die Änderungen nach quarto render werden nicht angezeigt. Häufig hilft die Tastenkombination StrgStrg + F5F5 (Windows, Linux); cmdcmd + shiftshiftRR (Mac) im Browser und die Seite wird vollständig aktualisiert dargestellt.
Weitere Schritte
Nach dem Schnellstart können Sie das Template auf drei Ebenen weiter bearbeiten. Für jede Ebene gibt es eigene Unterabschnitte.
Design und Layout anpassen: Sie passen die Gestaltung der HTML-Seiten einer Corporate Identity an.
Metadaten erfassen und pflegen: Sie befüllen die Metadatenfelder mit Ihren Angaben, um wirklichh FAIRedelte OER zu erstellen.
Inhalte erstellen: Sie ergänzen oder ändern Inhalte in der vorgesehenen
.qmd-Datei.
Wenn Sie anschließend eine Veröffentlichung planen, ist der Abschnitt Bereitstellung relevant. Dort wird beschrieben, wie HTML-Ausgaben je nach Szenario bereitgestellt werden können, ohne dass eine öffentliche Online-Publikation zwingend erforderlich ist.
Projektstruktur
Quarto bietet sehr umfangreiche Möglichkeiten zur Steuerung von Struktur, Gestaltung, Metadaten und Ausgabe. Wer diese Möglichkeiten vollständig ausschöpfen möchte, landet jedoch schnell bei sehr langen und unübersichtlichen Headern in einzelnen .yml- oder .qmd-Dateien.
Das Template begegnet diesem Problem durch eine Aufteilung der Konfiguration auf mehrere Dateien. Statt viele unterschiedliche Aspekte in einem einzigen Header zu bündeln, werden Konfiguration, Metadaten, Gestaltung und Inhalte in jeweils eigenen Dateien gepflegt. Dies erhöht die Lesbarkeit, erleichtert Anpassungen und reduziert die Gefahr unbeabsichtigter Änderungen.
Die Projektstruktur des Templates ist daher bewusst klar und übersichtlich gehalten. Sie orientiert sich an der Trennung von Konfiguration, Metadaten, Inhalten und unterstützenden Ressourcen:
Dateien und Verzeichnisse im Template:
├── assets
│ ├── csl
│ │ ├── american-journal-of-archaeology.csl
│ │ ├── antiquity.csl
│ │ ├── apa.csl
│ │ ├── bulletin-de-correspondance-hellenique.csl
│ │ ├── deutsches-archaologisches-institut.csl
│ │ ├── internet-archaeology.csl
│ │ ├── README
│ │ └── rgk
│ │ ├── LICENSE
│ │ ├── README
│ │ └── roemisch-germanische-kommission.csl
│ ├── fonts
│ │ └── pt_sans
│ │ ├── OFL.txt
│ │ ├── pt-sans-v18-latin_latin-ext-700italic.woff2
│ │ ├── pt-sans-v18-latin_latin-ext-700.woff2
│ │ ├── pt-sans-v18-latin_latin-ext-italic.woff2
│ │ └── pt-sans-v18-latin_latin-ext-regular.woff2
│ └── n4o_oer_html.scss
├── _autor_innen.yml
├── bibliographie.bib
├── _brand.yml
├── data
├── img
│ └── placeholder.png
├── _layout.yml
├── _oer_metadata.yml
├── _quarto.yml
└── template.qmdMehrere Dateien im Projektverzeichnis beginnen mit einem Unterstrich _. Diese Benennung folgt einer Konvention in Quarto-Projekten. Dateien mit einem führenden Unterstrich werden nicht als eigenständige Inhalte gerendert, sondern dienen der Konfiguration, Beschreibung und Strukturierung. Sie bilden den technischen Rahmen des Projekts.
Das Verzeichnis assets enthält unterstützende Ressourcen, die für Gestaltung und Ausgabe benötigt werden. Dazu gehören unter anderem Zitationsstile, Schriftarten und weitere gestalterische Dateien.
Innerhalb dieses Verzeichnisses ist die Datei n4o_oer_html.scss von besonderer Bedeutung. Sie definiert projektspezifische Stilregeln für die HTML-Ausgabe und ergänzt die in _brand.yml festgelegten Gestaltungsvorgaben.
Weitere Verzeichnisse wie img oder data dienen der Ablage von Abbildungen und Datensätzen, die in den Materialien verwendet werden können.
_quarto.yml ist die zentrale Projektkonfiguration: Sie definiert grundlegende Eigenschaften des Projekts, unter anderem den Dokumenttyp, globale Optionen sowie die Einbindung weiterer Konfigurations- und Metadatendateien. Änderungen an dieser Datei wirken sich immer auf das gesamte Projekt aus. Da einige Templates wie Übung oder Skript jeweils nur eine HTML-Datei erzeugen und die dafür notwendigen Angaben alle in den anderen Dateien vorhanden sind, ist die _quarto.yml der Templates nahezu leer. De facto braucht es aber eine _quarto.yml-Datei, um das Repository als Template über GitHub anbieten zu können.
.qmd-Dateien sind die Inhaltsdateien des Templates: Sie enthalten den Text der Übung oder des Skripts und sind der primäre Arbeitsort für inhaltliche Anpassungen. In dieser Datei werden Inhalte ergänzt, verändert oder entfernt. Projektweite Einstellungen oder strukturierte Metadaten werden hier bewusst nicht gepflegt.
_oer_metadata.yml enthält strukturierte Metadaten zur Beschreibung der Übung als Open Educational Resource: Hier werden Angaben erfasst, die für Auffindbarkeit, Nachnutzbarkeit und maschinelle Verarbeitung relevant sind. In ihr können zusätzlich sogenannte Quarto-Shortcodes definiert werden, also benannte Platzhalter, die an zentraler Stelle einmal festgelegt und anschließend im gesamten Projekt wiederverwendet werden. Diese Shortcuts können in .qmd-Dateien wie normale Variablen referenziert werden und erleichtern es, wiederkehrende Angaben konsistent zu verwenden und bei Änderungen nur an einer Stelle anzupassen.
_autor_innen.yml dient der Erfassung von detaillierten Angaben zu Autor:innen: Sie ermöglicht eine konsistente Pflege von Namen, Rollen und weiteren beschreibenden Informationen und kann an mehreren Stellen im Projekt referenziert werden. Auch diese Datei wird nicht direkt gerendert, sondern in andere Projektbestandteile eingebunden.
_brand.yml steuert Aspekte der visuellen Gestaltung und der Corporate Identity: Hier werden unter anderem Logos, Farben, Schriften und weitere gestalterische Parameter definiert. Die Datei bildet die Grundlage für eine institutionelle Anpassung des Erscheinungsbildes, ohne Inhalte verändern zu müssen.
_layout.yml definiert strukturelle Aspekte der Ausgabe: Sie steuert, wie Inhalte angeordnet werden und welche Layoutelemente verwendet werden. Die Trennung von Layout und Inhalt ermöglicht es, die Darstellung zu verändern, ohne die inhaltlichen Dateien anzupassen.
bibliographie.bib enthält die bibliographischen Referenzen im BibTeX-Format: Sie wird für Zitate und Literaturverweise genutzt und ist unabhängig von den eigentlichen Inhalten organisiert. Auf diese Weise können Literaturangaben gepflegt und in unterschiedlichen Kontexten wiederverwendet werden. Für die Zitierweise stehen in /assets/csl/ einige relevante Stile bereit, die in der Datei oer_metadata.yml mit dem key csl: festgelegt werden können.
Beim Rendern des Projekts erzeugt Quarto eine HTML-Ausgabe in einem separaten Output-Verzeichnis - wenn nicht anders angegeben im Verzeichnis _site. Dieses Verzeichnis enthält ausschließlich automatisch erzeugte Dateien und ist nicht Teil der Bearbeitung. Es wird bei jedem erneuten Rendern überschrieben.
Die klare Benennung und Trennung der Dateien im Template ermöglicht es, Anpassungen gezielt vorzunehmen. Inhalte, Metadaten, Gestaltung und Konfiguration sind voneinander getrennt und können unabhängig weiterentwickelt werden.
Kurzübersicht mit wesentlichen Funktionen:
| Datei | Funktion |
|---|---|
n4o_oer_html.scss |
Enthält projektspezifische Stilregeln für die HTML-Ausgabe und ergänzt die Branding-Einstellungen |
_autor_innen.yml |
Erfasst Autor:innenangaben und Rollen in strukturierter Form |
bibliographie.bib |
Verwaltet bibliographische Referenzen für Zitate und Literaturverweise |
_brand.yml |
Definiert die Corporate Identity, einschließlich Logos, Farben, Schriften und visueller Parameter |
_layout.yml |
Steuert die strukturelle Anordnung von Inhalten und Layoutelementen |
_oer_metadata.yml |
Enthält strukturierte Metadaten zur FAIR-orientierten Beschreibung der OER |
_quarto.yml |
Zentrale Projektkonfiguration und Einbindung weiterer Dateien |
.qmd |
Enthält die Inhalte und Struktur des jeweiligen Dokuments |
Alle genannten Dateien sind ausführlich kommentiert, sodass ihre Funktion und die vorgesehenen Anpassungspunkte direkt im jeweiligen Dateiinhalt nachvollzogen werden können.
Die hier beschriebene Projektstruktur bezieht sich auf die aktuell verfügbaren Templates, die bewusst einfach gehalten sind. In Planung befinden sich die Templates Kursbaustein und Kurs. Da Kurse aus Kursbausteinen zusammengesetzt werden und hierfür eine deutlich komplexere Projektstruktur erforderlich ist, wird diese Beschreibung ergänzt, sobald die entsprechenden Templates veröffentlicht sind.
Quarto kann Projekte in viele weitere Ausgabeformate rendern. Diese Formate erfordern jedoch zusätzliche Abhängigkeiten und eine erweiterte Konfiguration. Aus allgemeinen Erwägungen und im Sinne einer FAIRen Bereitstellung konzentrieren sich die Templates daher auf die Ausgabe von HTML.
Disclaimer: Einsatz von LLM
Bei der Erarbeitung dieser Website wurde ChatGPT-5.2 zur Unterstützung eingesetzt. Die Nutzung umfasste die Strukturierung und Diskussion der Inhalte sowie inline-code grammatikalische und orthographische Korrekturen. inline-code Es wird ausdrücklich darauf hingewiesen, dass die endgültige Verantwortung für die inhaltliche Richtigkeit beim Autor liegt.
–>