Der Yaml-Header
Auf dieser Seite
Der Yaml-Header enthält die Parameter der Projektverwaltung. Alle dort verwendeten Einträge sind gleichzeitig Variablen, deren Werte beim Export vielfältige Aufgaben übernehmen können. Neben den Projektparametern können beliebig viele individuelle Variablen definiert werden.
Aufbau des Yaml-Headers
Der Yaml-Header muss in der ersten Zeile der Datei beginnen. Er wird mit einer Zeile eingeleitet, die drei Minus-Zeichen am Zeilenanfang hat. Mit so einer Zeile wird er auch abgeschlossen. Eine Leerzeile beendet den Yaml-Header ebenfalls. Das ist eine bewusste Abweichungvom Yaml-Standard, die undefinierte Zustände verhindert, falls die schließende Zeile vergessen wurde.
Jeder Eintrag im Yaml-Header hat dieses Muster:
Beispiel 1, Verwendung s. Beispiel 2
muster : Egal wie lange diese Zeile ist: So lange kein »Wagenrücklauf« („ENTER“) das Zeilen-/Absatzende markiert, ist alles hinter dem ersten Doppelpunkt Inhalt des Parameters oder der Variable. Die Leerzeichen vor und hinter dem Namen und dem Inhalt werden ignoriert.
Maßgeblich für die Interpretation ist der erste Doppelpunkt ab Zeilenanfang. Bis dort wird der Inhalt als Variablenname interpretiert. Ab dort ist es der Wert der Variable. Leerzeichen am Anfang und Ende des jeweiligen Bereichs werden ignoriert.
Einträge im Yaml-Header können mit der Kommentarfunktion ausgeblendet werden und dann beim Export ignoriert. Sie werden trotzdem vom Yaml-Header-Check erkannt, damit kein versehentliches automatischen anfügen eines ausgeblendeten Parameters erfolgt.
Projektparameter
Für die Projektsteuerung stehen die nachfolgenden Parameter zur Verfügung.
| Editor-Parameter | erforderlich | Funktion |
|---|---|---|
| project | ✔ | Der Name der Projektkonfiguration und des Projekt-Ordners im Projektverzeichnis. |
| in | ✔ | Der relative Pfad ausgehend vom Basisverzeichnis und Name der Datei, der beim Speichern vorgeschlagen wird. Ohne Dateityp wird automatisch der Default verwendet (s. Konfiguration, SET) |
| media | ✔/✗ | Der relative Zielpfad für Medien-Dateien, die in diese Datei importiert werden (Drag & Drop oder Menübefehl). Ein hier angegebener Pfad ergänzt den Basispfad für Medien, in den sie beim Einfügen in den Text automatisch kopiert werden. Beim Einfügen ohne Ein auskommentierter Medienpfad deaktiviert den FTP-Upload für alle verknüpfte Medien. Damit kann das wiederholte Hochladen von Medien bei Textänderungen verhindert werden (s. auch Kein Medien-FTP-Upload). |
| layout | ✔/✗ | Die Format-Datei für die Ausgabe. Layouts eines Projekts müssen im zugewiesenen Layout-Ordner liegen. Ohne Layout wird der Editor-Text als „HTML-Rumpf“ in die Zieldatei geschrieben. |
| out | ✗ | Der relative Pfad zum Basisverzeichnis und der Dateiname für den Export. Fehlt dieser Eintrag, wird Pfad und Name von Typischerweise wird das |
| lang | ✗ | Dieser Eintrag erzeugt automatisch ein „Sprachverzeichnis“, das dem Statt einer Sprache kann ein beliebiger Text vorangestellt werden, beispielsweise für Entwicklungsvarianten einer Webseite. |
| stage | ✗ | Dieser Eintrag wird dem Ausgabepfad („out“) voran gestellt. Damit können Varianten Webseiten in einem speziellen Verzeichnis vorbereitet werden, das zwar der Strutkur der Webseite folgt, durch das „stage“-Verzeichnis jedoch aus der tatsächlichen Seitennavigation ausgenommen ist. Diese Variable kann mit Platzhalter-Funktionen kombiniert werden. Damit können die verschiedenen Varianten beim Export gesteuert werden. |
| upload | ✗ | Dieser Parameter ist ausschließlich bei FTP-Funktionen relevant: Benötigte Elemente können damit auf die Website geladen werden.
Der |
| delete | ✗ | Dieser Parameter ist ausschließlich bei FTP-Funktionen relevant: Er kehrt das Hochladen der Dateien um.
Die Funktionalität hängt von weiteren Schaltern ab, s. Löschen per Upload. |
filewithoutext-
Diese Editor-Variable enthält den
out-Namen und Pfad ohne Dateierweiterung. Wird der Parameterlangverwendet, wird das berücksichtigt.
Der Minimal-Yaml-Header
Ohne die nachfolgenden Mindesangaben werden rudimentäre Standards (ausgehend vom Programmdatei-Pfad) verwendet:
Project: Projektname
in: \[pfad/]Datei.\[md|txt|…]
media: [pfad]
In der Projekt-Konfiguration kann ein Standard-Yaml-Header vorgegeben werden, der für neue Dateien verwendet wird. Bereits erstellte Dateien werden damit beim Öffnen mit dem Yaml-Check (s.o.) abgeglichent.
Variablen
Die Schreibweise von Variablen ist irrelevant:
Variable = VARIABLE = variable = VaRiAbLe
Variablen werden in der exportierten Zieldatei erst nach dem Expandieren der Module ersetzt. Deshalb können sie in der Layout-Datei, in Modulen) und Funktionen verwendet werden.
Konventionen
Variablen aus dem Yaml-Header sind Platzhalter für deren Inhalt beim Export. Eine fehlende (oder auskommentierte) Variable entspricht einer leeren: Der Platzhalter wird aus dem Export entfernt.
- Besonderheit
-
Beginnt der Name einer fehlenden Variablen mit einem Ausrufezeichen, wird die gesamte Zeile im Ergebnis gelöscht, in der sie steht.
So lassen sich umschließende Code-Elemente entfernen, die zu einer fehlerhaften Formatierung führen könnten.
Variablen können beliebig oft verwendet werden, sie werden an allen Fundstellen ersetzt.
Erkennungsmerkmal ist der Variablenname, der mit jeweils drei Prozenzt-Zeichen umschlossen ist:
%%%variablenname%%%
Die Verwendung von Variablen in Modulen und Funktionen erfordert Umsicht:
- Eine „!variable“ löscht zu guter Letzt einen eingefügten Code, wenn sie fehlt.
- In Modulen sollten Routinen vorgesehen sein, die eine fehlende, „leere“ Variable auffangen.
- Bei Funktionen kann eine Auffangroutine mit
choiceabgebildet werden.
- Daten, die mit Funktionen oder Modulen in das Ergebnis eingefügt werden, können Variablen enthalten, die in der Ausgangsdatei einen anderen Zweck ahben oder dort fehlen. Sie werden dennoch wie Varialben behandelt.
- Mehrere Variablen mit „!“ im selben Absatz entsprechen einer „oder“ Funktion: Eine fehlende Varialbe genügt, damit der Absatz (bzw. Die Code-Zeile) entfernt wird.
Es finde keine Kontrolle statt, ob sinnvoller Code entsteht..
Die Möglichkeiten sind ausgesprochen komplex, deshalb nachfolgen einige …
Verwendungsbeispiele
Beispiel 2, Variablendefinition in Beispiel 1
In diesem Absatz wird der Text die Variable aus „Beispiel 1“ angehängt: %%%muster%%%
Ausgabe:
In diesem Absatz wird der Text die Variable aus „Beispiel 1“ angehängt: Egal wie lange diese Zeile ist: So lange kein »Wagenrücklauf« („ENTER“) das Zeilen-/Absatzende markiert, ist alles hinter dem ersten Doppelpunkt Inhalt des Parameters oder der Variable. Die Leerzeichen vor und hinter dem Namen und dem Inhalt werden ignoriert.
Was herauskommt, wenn…
Die nachfolgenden Varianten zeigen die Möglichkeiten, wie sich ein Absatz mit zwei Variablen verändern lässt.
- Diese Zeile steht im Editor:
-
%%%!p1%%% Was passiert %%%p2%%% mit diesem Absatz?
- Variante 1: Es gibt beide Variablen
-
---
!p1:Frage:
p2: beim ersetzen
---Ausgabe:
Frage: Was passiert beim Ersetzen mit diesem Absatz?
- Variante 2: Die „Ausrufezeichen“-Variable ist leer
-
---
!p1:
p2: beim ersetzen
---Ausgabe:
Was passiert beim Ersetzen mit diesem Absatz?
- Variante 3: Die „normale“ Variable ist auskommentiert
-
---
!p1:
??p2: beim ersetzen
---Ausgabe:
Was passiert mit diesem Absatz?
- Variante 4: Die „Ausrufezeichen“-Variable ist auskommentiert
-
---
??!p1: Frage:
p2: beim ersetzen
---Ausgabe:
Die Variable „!p1“ ist mit „??“ auskommentiert, sie „fehlt“. Weil sie mit „!“ beginnt, wird der Absatz vollständig aus der Ausgabe entfernt.
Das „Auslöschen“ ganzer Absätze kann z.B. die Darstellung von Elementen im Layout steuern, z.B. die erste Überschrift auf der Seite, die „eigentlich immer, aber manchmal eben doch nicht“ ganz am Anfang stehen soll.