Funktionen
Auf dieser Seite
Dieses Untermenü stellt Nachbearbeitungen in der Export-Datei bereit, die über das Ersetzen oder Entfernen der Editor-Variablen und Yaml-Variablen hinaus gehen.
Funktionen teilen sich in Präprozessor- und Postprozessor-Funktionen. Sie werden beim Erzeugen der Ausgabe angewandt. Präprozessor-Module verändern die Markdownquelle. Darin werden Module und Yaml-Variablen ersetzt. Abschließend werden Postprozessor-Module im HTML-Code abgearbeitet.
Ob valider Code ausgegeben wird, hängt von der Sorgfalt bei der Verwendung der Module, Variablen und Funktionen ab.
Allgemeine Regeln
$$$ Funktionsname [Zuordnung] [:] [Wertzuweisung] $$$
-
- Falsch geschriebene, unbekannte oder ungenutzt gebliebene Funktionen werden vollständig (
$$$…$$$
) entfernt. - Funktionsname = FUNKTIONSNAME = Funktionsname, Zuordnung = ZUORDNUNG = zuordnung
- Funktionsname und Zuordung müssen aus Buchstaben, Zahlen und ausgewählten Zeichen ≠ „:“ oder Leerzeichen bestehen.
- Der Funktionsname ist unveränderlich von
OSE vorgegeben - Die Zuordnung kann – abhängig vom Funktion – entfallen oder eine eingeschränkte Schreibweise haben (s. Inhaltsverzeichnis).
- Die Wertzuweisung darf beliebig lang sein und beliebige Zeichen enthalten. Hier können einige Zeichen eine besondere Eigenschaft für die Funktion haben (s. Wahl)
- Funktionsname, Zuordnung und Wertzuweisung werden von den Funktionsbegrenzungen oder mindestens einem Leerzeichen oder dem Doppelpunkt voneinander getrennt. Zur besseren Leesbarkeit dürfen weitere Leerzeichen verwendet werden.
- Falsch geschriebene, unbekannte oder ungenutzt gebliebene Funktionen werden vollständig (
Ineinander verschachtelte Funktionen verstümmeln die Zieldatei.
Präprozessor
Regeln
- Der Yaml-Header importierter Markdown-Dateien wird ignoriert.
- Markdown-Funktionen sollten vorzugsweise freistehend in einem Absatz verwendet werden.
- Eingefügte Dateien werden grundsätzlich in einen Abschnitt (
<div>
) gesetzt, weshalb eine Einfügung innerhalb eines Absatzes dessen Struktur zerstört. - Es findet keine Prüfung statt, ob die eingefügten Dateien tatsächlich Markdown enthalten.
- Es findet keinerlei Interpretation beim Einfügen des Dateiinhaltes statt.
- Das eingefügte Markdown wird bearbeitet, als stünde es in der Quelldatei, von der aus das eingefügte Markdown referenziert wurde.
- Präprozessor-Module können ausschließlich in der Markdown-Quelle verwendet werden.
- Bitte beachten:
-
- Yaml-Variablen werden mit den Werten der aktuellen Quelldatei ersetzt.
- Relative Referenzen gelten relativ zur aktuellen Quelldatei.
Präprozessor-Funktionen werden vor der Bearbeitung des Markdown-Codes eingefügt. Das erfolgt ohne Rücksicht auf ein vorangestelltes Kommentarzeichen. Deshalb führt „auskommentieren“ von Präprozessor-Funktionen zu unvorhersehbaren, mehr oder minder verstümmelten Ergebnissen mit – mutmaßlich – unerwünschtem Inhalt.
Die „Lesezeit-Variablen“ werden nach dem Präprozessor anhand des dann vorhandenen Markdowns berechnet. Diese Ermittlung erfolgt unabhängig vom Status des „Worte zählen“-Schalters, weshalb die Variablen bei der Ausgabe immer einen gültigen Wert für die aus dem Markdown erzeugte Ausgabe haben.
MD-Datei: mdfile
Fügt eine referenzierte Markdown-Datei aus dem Projekt-Markdown-Verzeichnis ein.
mdfile kennung [klasse] : relativer Pfad\Dateiname
- Dem übergebenen Dateipfad wird der Markdown-Basispfad des Projekts vorangestellt.
- Die eingefügte Datei wird mit einem Abschnitt
<div class="…">…</div>
umschlossen. - Wird eine Klasse übergeben, wird diese verwendet, andernfalls erhält der Abschnitt eine Klasse mit der Kennung der Funktion.
- Innerhalb der aktuellen Markdown-Datei muss die Kennung eindeutig sein.
MD-Verzeichnis: mddir
Fügt alle Dateien aus dem gewählten Verzeichnis in die aktuelle Datei ein.
mddir kennung [k1] [k2] : relativer Pfad
- Dem übergebenen Dateipfad wird der Markdown-Basispfad des Projekts vorangestellt.
- Sowohl die gesamte Einfügung, als auch jede einzelne Datei wird mit einem Abschnitt
<div class="…">…</div>
umschlossen. - Werden keine Klassen übergeben, wird für alle Abschnitte die Kennung als Klasse vergeben.
- Wird eine Klasse übergeben (k1), gilt diese für die Datei-Abschnitte.
- Werden zwei Klassen übergeben, gilt die erste (k1) für den umschließenden, die zweite (k2) für die Datei-Abschnitte.
MD-Pfad: mdtoc
Fügt eine verlinkte Liste aller Dateien aus dem gewählten Verzeichnis in die Aktuelle Datei ein.
Für eine komfortable Verwendung der Funktion werden bedarfsweise doch Yaml-Variablen aus den referenzierten Dateien verwendet. Diese können über die Zuordnung individuell gewählt werden.
mdtoc kennung [title] [sort] [more] : relativer Pfad
- Verfügt die Funktion über keine weiteren Angaben außer der Kennung und dem Pfad, wird der Yaml-Eintrag
title
als Text für den Hyperlink unterstellt. - Statt dessen kann ein beliebiger Yaml-Eintrag verwendet werden. Dieser wird als erster Eintrag in der Zuordnungsliste erwartet. Fehlt diese Yaml-Definition wird ein Ersatztext verwendet.
- Ist ein zweiter Yaml-Eintrag zugeordnet, wird dieser zum Sortieren verwendet. Fehlt er, wird auf den Titel zugegriffen.
- Ist ein dritter Yaml-Eintrag zugeorndet, wird dessen Inhalt unter den Link als Beschreibungstext eingefügt.
- Wird im Yaml-Header einer zu verlinkenden Datei der Projekt-Parameter
delete
gefunden, wird diese Datei aus der Liste ausgeschlossen: Der Parameter verhindert den Export auf den Server, also wird diese Datei (wahrscheinlich) dort fehlen und wäre deshalb ein „toter“ Link.
Die Formatierung
Ohne Beschreibungstext wird jeder Link als Absatz in die Markdown-Datei eingefügt:
[Titel]〈Link zur Datei〉
Mit Beschreibungstext wird ein Definitionslisten-Eintrag erzeugt:
[Titel]〈Link zur Datei〉
: Beschreibung
Die Formatierung kann mit umschließenden Klassen und nachgeordneten Definitionen für die Definitionsliste darin frei gestaltet werden.
<div class="small">
$$$ mdtoc einfuegen title rang description : /editor/einfuegen/ $$$
</div>
- Arbeitsmarken ▶
-
Dauerhafte Marken im Markdown plazieren.
- Editor-Variablen ▶
-
Editor-Variablen
- Einfügen
-
Übersicht Menü Einfügen
- Funktionen
-
Funktionen bieten strukturelle Erweiterungen der Ausgabe.
- Fußnote einfügen
-
Einfügen von Fußnoten.
- Hyperlink einfügen
-
Erzeugung von Hyperlinks
- Modul einfügen…
- Diese Seite muss noch mit Leben gefullt werden.
- Projekt-Querverweis…
-
Verweise auf Textstellen der Webseite.
- Querverweis(e)…
-
Seiteninterne Querverweise und Inhaltsverzeichnisse.
- Wrapper…
-
Einfügen von „Wrappern“ (Abschnitten, DIV).
Die Sortierung erfolgt mit der Methode „A11…A101“.
Das ermöglicht eine leicht erstell- und pflegbare Rangfolge über eine „Rang“-Yaml-Variable oder das (rückwärts ausgegebene) Bearbeitungsdatum.
Postprozessor
Regeln
- Einige Funktionen können über mehrere Absätze hinweg eingesetzt werden. Es hängt vom Einzelfall ab, ob das erforderlich oder sinnvoll ist.
- Innerhalb der Funktionsbegrenzungen
$$$
werden Funktionen vom Markdown-Parster als Markdown angesehen, Auszeichnungen entsprechend ersetzt.
Das ermöglicht Strukturen, die mit einfachem Markdown unmöglich sind oder die Integration von HTML-Code erfordern würden. - Postprozessor-Funktionen können in allen Teilen, also neben der HTML-Quelle auch in der Layout-Datei, verwendet werden.
Wahl: choice
Der Wahlschalter kann variablen Text abhängigg Yaml-Variablen in einen Absatz oder als Überschrift einfügen.
choice
wird vorrangig bei den Präprozessor-Funktionen abgearbeitet. Das ermöglicht optionale Parameter in den nachfolgenden Funktionen.
[<]$$$ choice [1..6|+]name :[variante 1 | variante 2 | …] $$$[>]
Es können beliebig viele Werte, getrennt durch |
(ALT
<
- Taste) angegeben werden.
Ausgegeben wird der erste von rechts gefundene Wert, der länger als 0 Zeichen ist (umschließende Leerzeichen werden entfernt). Die Funktion wird durch den gefundenen Text ersetzt.
Hat choice
ein +
an einer beliebigen Stelle in der Zuordnung, wird hinter dem Text ein gleichnamiger Anker erzeugt.
Beginnt die Zuordnung mit einer Zahl, wird ein „Überschrift-Rumpf“ erzeugt. Deshalb muss die Funktion für einen validen Code mit <…> umschlossen sein. Ein womöglich enthaltenes „+“ wird in diesem Fall ignoriert: Die Überschrift bekommt einen ID, damit sie z.B. aus einem generierten Inhaltsverzeichns angesprungen werden kann.
Nützlich ist das beispielsweise für Überschriften im Layout, die normalerweise mit dem title
erzeugt werden, doch wahlweise mit einem anderen Text gefüllt werden oder leer bleiben sollen.
Aus
<$$$ choice 4heading : Seitentitel | %%%Ersatztitel%%% $$$>
wird
<h4 id="auswahl-der-ueberschrift">Auswahl der Überschrift</h4>
Die Wahlfunktion kann darüber hinaus mit der „Löschfunktion“ (vorangestelltes „!“) von Yaml-Variablen kombiniert werden. Die Yaml-Variablen werden vor den Funktionen abgearbeitet.
„choice“ wird vor „toc“ abgearbeitet, weshalb die Position der Funktionen innerhalb der Seite keine Rolle spielt.
Anker: id
Ermöglicht die Erzeugung beliebiger Sprungmarken im Text. Wahlweise wird ein markierter Block oder ein anzugebender Text übergeben. Dieser Text wird als sowohl als unsichtbarer Anker als auch im Text ausgegeben:
»$$$ id: Dieser Anker $$$« ist zusätzlich eine Sprunmarke.
»<a id="dieser-anker"></a>Dieser Anker« ist zusätzlich eine Sprungmarke.
Es gelten den Regeln für die ID-Erzeugung. Die Position kann innerhalb der Datei und von anderen Dateien mit einem Hyperlink angesprungen werden:
- Beispiel
-
[Zum ersten Absatz]〈#$$$ mkid : Dieses Untermenü $$$ ""〉
→ Zum ersten Absatz
Ein Anker kann nahezu überall plaziert und umschließend formatiert werden.
- Hinweis
-
Browser springen mit der aktiven Marke zu Hyperlinks auf der gleichen Seite. Das kann ein Rollen auslösen, mit dem die Marke am Seitenanfang oder -ende sichtbar wird. Befindet sich die Marke bereits im sichtbaren Bereich, wird der Sprung nur wahrnehmbar, wenn eine entsprechend Stilvorlage die aktive Marke hervorhebt. Bei Ankern ist diese Marke bestensfalls einen Strich breit.
Es findet keine Dubletten-Prüfung statt.
- Querverweise
-
- Mit Modulen, genauer mit markierten Parametern von Modulen, können ebenfalls Anker erzeugt werden.
- Mit der Wahl-Funktion wird automatisch der zur Wahl passende Anker erzeugt.
ID erzeugen: mkid
Diese Funktion ist primär für Module gedacht, in denen aus übergebenen Parametern ein ID erzeugt werden soll. Das Ergebnis entspricht dem Menübefehl.
- Beispiel
-
$$$ mkid : Hier steht Text $$$
→ hier-steht-text
Anwendungsbeispiel: „Glossar-Links erzeugen“
Platzhalter: insert
Markiert die Einfügeposition für den Inhalt eines Platzhalters. Der Platzhalter kann an beliebiger Stelle im
Ist beim Aufruf des Befehls ein Text markiert, wird er als Bezeichner des Platzhalters übernomen, ohne Prüfung, ob die Markierung die dafür geltenden Regeln erfüllt. Andernfalls wird der Cursor an der Position plaziert, an der eine Zuordnung vorgenommen werden muss.
Ein Platzhalter ohne korrespondierender Definition wird aus dem Ergebnis entfernt.
Platzhalter werden ohne Rücksicht auf Strukturen, d.h. innerhalb von PHP-Code, als Code formatierte Abschnitte, … — überall — ersetzt. Es findet keine Kontrolle statt, ob das darstellbaren Code ergibt.
Platzhalter: define
Einem mit »insert name« erzeugten Platzhalter-Namen wird mit »define name: …« ein Inhalt zugewiesen.
Der Umfang ist nahezu beliebig. Von einem einzelnen Wort bis zu unzähligen Absätzen inklusive Modulen, etc. ist möglich. Die Art der Einfügung lässt sich durch die Art der Definition beeinflussen:
- Folgt der Definition direkt im Absatz ein Inhalt (
$$$ define name : Inhalt… $$$
), wird dieser ohne umschließende Strukturmerkmale (Absatz, Abschnitt) übernommen. - Steht
$$$ define name :
in einer einzelnen Zeile, gefolgt von Absätzen, die mit einer allein stehenden Schlussmarke$$$
in einem Absatz beendet wird, wird der Abschnit als Block mit<DIV>…</DIV>
umschlossen.
define Szenarien
Nachfolgend einige Beispiele, welchen Einfluss die Position des $$$insert … $$$
und der Struktur des damit verwiesenen $$$ define … :
auf die Ausgabe hat. Der mit dem jeweiligen Beispiel erzeugte Code kann mit der Quelltext-Funktion des Browsers untersucht werden.
Variante 1 ✔
Funktionsmarken im Text eines Absatzes : Der umschlossene Inhalt wird rückstandslos entnommen und ohne umschließenden Absatz-Tag in einem Platzhalter eingefügt.
$$$ insert variante1 $$$
Aus dem darunter liegenden Absatz wird Text entnommen $$$define variante1: Das ist der Inhalt von Variante 1. $$$ und darüber eingesetzt.
Ausgabe
Aus dem darunter liegenden Absatz wird Text entnommen und darüber eingesetzt.
Variante 2 ✔
Funktionsmarken umschließen den Inhalt eines Absatzes : Der umschlossene Inhalt wird ohne Absatz-Tags in einem Platzhalter eingefügt, der dann leere Absatz wird entfernt.
- $$$insert variante2 $$$
$$$ define variante2:Aus diesem Absatz wird Variante 2 entnommen.$$$
Ausgabe
Variante 3 ✔
Funktionsmarken alleinstehend jeweils in einem Absatz: Die dazwischenliegenden Zeilen werden vollständig übernommen, die Funktionsmarken hinterlasssen keine leeren Absätze
Das ist die favorisierte Variante, die der eingefügte Block vorschlägt.
$$$insert Variante3 $$$
$$$define variante3:
::: info
Dieser Abschnitt wird in der verwendeten Form hervorragend funktionieren und in Variante 3 eingefügt.
Bei der Verarbeitung wird dieser Bereich zusätzlich mit einem HTML-Block [nw "`<div>Variante 3</div>`"] als strukturierendes Element umschlossen. Innerhalb dieses Bereichs können daher weitere Struktur-Elemente, wie z.B. Zitate, weitere Blöcke, Aufzählungen, …, verwendet werden.
:::
$$$
„nw“ ist ein Modul, „info“ ein CSS-Stil dieses Projekts.
Ausgabe
Dieser Abschnitt wird in der verwendeten Form hervorragend funktionieren und in Variante 3 eingefügt.
Bei der Verarbeitung wird dieser Bereich zusätzlich mit einem HTML-Block <div>Variante 3</div>
als strukturierendes Element umschlossen. Innerhalb dieses Bereichs können daher weitere Struktur-Elemente, wie z.B. Zitate, weitere Blöcke, Aufzählungen, …, verwendet werden.
Damit dieser Ansatz wie gezeigt funktioniert, dürfen hinter den Einfügemarken bzw. dem Doppelpunkt der define
-Funktion keine Leerzeichen stehen.
Variante 4 ✗
Funktionsmarken beginnen/enden in einem Absatz mit Inhalt, überspannen mehrere Zeilen: Das wird verstümmelten Code erzeugen, es sei denn, im Inhalt ist am Anfang/Ende ein HTML-Absatzbegrenzer von Hand angegeben und der Platzhalter kann damit etwas anfangen.
- $$$insert Variante4 $$$
Aus diesen Absätzen wird $$$ define variante3: Das wird kein gutes Ende nehmen.
Denn es entsteht kein valider HTML-Code. Neben dem Abschnitt, in dem der Platzhalter steht, beschädigt es womöglich die „Teilabsätze“. Hier fügen sie sich „zu einem Absatz“ zusammen.$$$ Variante 3 entnommen.
Ausgabe
Denn es entsteht kein valider HTML-Code. Neben dem Abschnitt, in dem der Platzhalter steht, beschädigt es womöglich die „Teilabsätze“. Hier fügen sie sich „zu einem Absatz“ zusammen.
Aus diesen Absätzen wird Variante 4 entnommen.
In diesem Fall ist der Fehler moderat und wird von den meisten Browsern kompensiert: Es fehlt der Absatzanfang (<p>
) des ersten, und das Absatzende des letzten Absatzes (</p>
).
Inhalt: toc
Alternativ zumm manuellen Inhaltsverzeichnis durch eine Querverweis-Liste kann ein Überschriften-Verzeichnis der Seite mit der Funktions toc
erzeugt werden.
Alle Überschriften im erzeugten Dokument, inklusive der womöglich im Layout erzeugten, können gegenüber der Querverweise in der Arbeitsdatei einfließen. Dieses Verzeichnis entspricht immer dem Status der Datei beim Export, es „pflegt sich selbst“.
$$$ toc 1-6 : Inhaltsverzeichnis $$$
Regeln
- Das Verzeichnis wird mit
<DIV class="toc">
umschlossen. - Ein Inhaltsverzeichnis muss der einzige Eintrag in einem Absatz sein.
- Mit der Zuordnung kann der berücksichtigte Hierarchie-Bereich festgelegt werden.
- Ohne Zuordnung wird „1-6“ unterstellt
- Statt „-“ kann ein beliebiger Buchstabe verwendet werden, mit dem ggf. mehrere Verzeichnisse auf einer Seite unterschieden werden können.
- Als Wert kann optional eine Überschrift übergeben werden.
- Die Überschrift wird mit
<p class="toctitle">
umschlossen. Jeder Verzeichniseintrag erhält eine ID, der „toc-“ vorangestellt ist.
Bei mehreren Verzeichnissen mit gleichen Verweisen kommen diese IDs mehrfach vor!
„Für schick“ muss neben der umschließenden Klasse
.toc
, der Überschrift.toctitle
noch eine Formatierung für die Liste.toc ul
bzw. ggf. individuell für jede Stufe erfolgen.
Beispiel 1
$$$ TOC 3A4 : Beispiel 1 $$$
Beispiel 2
$$$ TOC 2B2 : Beispiel 2 $$$
Beispiel 3
$$$ TOC 1C1 : Beispiel 3 $$$
Die Buchstaben A,B,C adressieren das jeweilige Inhaltsverzeichnis.
Datei: file
$$$ file platzhalter : Dateipfad $$$
Im Ergebnis entspricht diese Funktion einem „include“ (PHP, HTML): Eine Datei aus dem Projektverzeichnis wird wie sie ist in die Ausgabedatei eingefügt. Der »Platzhalter« dient der zweifelsfreien Identifikation der Datei bei einem Fehler (hier provoziert):
Ladefehler: $$$ file platzhalter $$$
Der Datei-Pfad wird aus der Fehlermeldung entfernt. Für die Fehlersuche ist die Zuordnung ausreichend, der Pfad zu einer (fehlenden) Datei sollte aus mehreren Gründen kein Bestandteil einer Webseite sein.
Der wesentliche Unterschied zum „include“: Die geladene Datei ist fester Bestandteil des erzeugten Dokuments, während bei einem include die Enfügung jeweils im Augenblick des Seitenaufrufs erfolgt, also immer die aktuelle Version der eingefügten Datei verwendet wird.
Diese Funktion ist ein Behelf für Bedingungen, in denen „include“ keine Option ist (z.B. lokale Anwendung ohne aktive Umgebung, Webseiten mit maximalen Sicherheitseinschränkungen). In diesen Fällen müssen bei Änderungen der eingebetteten Datei(en) die davon betroffenen Seiten neu generiert werden (s. Projekt neu generieren).
Grundsätzlich kann eine beliebige, lokale Datei mit dieser Funktion in die Ausgabe integriert werden. Für den Verweis mit korrektem relativen Pfad gibt es den Datei-Befehl „Dateiverweis (lokal)“.
Eingefügte Dateien müssen validen Code enthalten, der sich strukturell korrekt in die erzeugte Ausgabe einfügt.
Es findet keine Kontrolle statt, ob die ausgewählte Datei eine funktionsfähige Export-Datei erzeugt.
Verzeichnis: dir
„dir“ ermöglicht das Einbetten aller Dateien eines Verzeichnisses in die Ausgabe.
Es findet keine Prüfung statt, ob die vorgefundenen Dateien dafür geeignet sind und das Ergebnis eine darstellbare Datei erzeugt.
Sinnvoll verwendbar ist dieser Befehl nur für Verzeichnisse, in denen HTML-Fragmente oder PHP-Skripte (soweit auf dem Server unterstützt) vorliegen.
- Das Einlesen erfolgt in alphabetischer Reihenfolge der Dateien im Verzeichnis.
- Jede Datei wird mit einer Blockmarke
<div>…</div>
umschlossen. - Die Funktion sollte alleinstehend in einer Zeile positioniert sein.
Wird ein Projekt vollständig neu erzeugt, müssen Seiten mit dieser Funktion explizit kontrolliert werden:
Das Verzeichnis, aus dem die Dateien eingelesen werden sollen, ist zum Zeitpunkt der Erstellung womöglich noch leer!
Ein Anwendungsbeispiel ist das hier in der Hilfe damit erzeugt Glossar.