Ad-Hoc HTML Plugin for DokuWiki

Dieses Plugin erlaubt es, bestimmte HTML-Tags in DokuWiki Code zu gebrauchen. Es ist auch die Grundlage für die anderen Ad-Hoc-Plugins.

Seit Version „Jack Jackrum“ ist die Möglichkeit, HTML-Tags in DokuWiki-Code einzufügen, nicht mehr in der Standardinstallation verfügbar (siehe htmlok). Diese Einschränkung ist sinnvoll, da diese Funktion auch zahlreiche Sicherheits-Implikationen hat, die von vielen technisch weniger versierten Nutzern nicht wirklich gut eingeschätzt werden können.

Gleichzeitig sind die HTML-Tags für erfahrenere Nutzer ein sehr hilfreiches Werkzeug, um Seiten zu strukturieren, oder um die Seiten barrierefrei zu gestalten (dies ist z.B. – aber nicht nur – für alle Behördenseiten verpflichtend. Siehe hierzu z.B.: Gesetze und Richtlinien zur Barrierefreiheit auf bund.de).

Aber zum Beispiel auch der Block hier oben rechts ist mittels <aside>- und <figure>-Tags ausgezeichnet, was ohne Zugriff auf diese Elemente im besten Fall nicht mehr semantisch korrekt, im schlimmsten überhaupt nicht ausführbar wäre.

Das folgende, einfache Beispiel zeigt, wie HTML im Wikitext benutzt werden kann:

Das <dfn #lemma><i :la>Ad Hoc</i> HTML Plugin</dfn> erlaubt mehr <b important>Flexibilität</b>
beim Gebrauch von <abbr "HyperText Markup Language">HTML</abbr>-Tags, ohne dass man sich mit
den **Komplikationen** und <strong warning>potentiellen Sicherheitsproblemen</strong>, die mit
voller <abbr>HTML</abbr>-Unterstützung kämen, herumschlagen muss.

Die folgenden HTML-Elemente werden von diesem Plugin unterstützt:

• <a> — “Anchor/Link”
• <abbr> – “Abbreviation”*
• <address> – “Address”
• <article> – “Article”
• <aside> – “Aside”*
• <b> – “Bring Attention To”* (“bold”)
• <bdi> – “Bidirectional isolate”
• <bdo> – “Bidirectional override”
• <cite> – “Citation”
• <details> – “Details”
  + <summary> – “Summary”
• <dfn> – “Definition”
• <div> – “Generic block”
• <dl> – “Description list”
  + <dt> – “Description term”
  + <dd> – “Description details”
• <em> – “Emphasis”
• <figure> – “Figure”*
  + <figcaption> – “Figure caption”*
• <header> – “Header”
• <h1> … <h6> – “Section Headings”
• <footer> – “Footer”
• <i> – “Idiomatic Text”* (“italic”)
• <kbd> – “Keyboard Input”
• <mark> – “Mark Text”*
• <pre> – “Preformatted”
• <q> – “Inline Quotation”*
• <s> – “Strikethrough”*
• <samp> – “Sample Output”
• <section> – “Section”*
• <small> – “Side content” (“smaller”)
• <span> — “Content Span”
• <strong> – “Strong importance”
• <time> – “Date/Time”
• <u> – “Unarticulated Annotation”* (“underline”)
• <var> – “Variable”

Die Links hinter jedem Element gehen zu den entsprechenden MDN-Seiten, wo die jeweiligen Elemente genauer beschrieben werden, einschließlich Anwendungsbeispiele. Leider sind diese nur auf Englisch verfügbar.

Ad-Hoc HTML benutzt eine eigene Syntax für die Elementattribute, die vor allem darauf ausgelegt ist, einfache Funktionen möglichst schnell und einfach zu machen und gleichzeitig mögliche Sicherheitsprobleme mit anderen Attributen (insbesondere den JavaScript-Attributen) zu vermeiden.

Grundsätzlich können Attribute keine Leerzeichen enthalten (für Ausnahmen, siehe unten), da dieses Zeichen als Trennung zwischen Attributen verwendet wird.

Jeder Bezeichner in einem Element, der einen gültigen Klassennamen darstellt, wird als HTML-Klasse verstanden.

Zum Beispiel wird „<b wichtig>“ wie folgt in HTML umgesetzt: „<b class="wichtig">“.

Es können beliebig viele Klassennamen verwendet werden. „<aside outline box float-right>“ wird erwartungsgemäß zu „<aside class="outline box float-right">“

Für ID-Attribute wird die CSS-Syntax verwendet, d.h. der ID-Name wird durch ein vorangestelltes „#” gekennzeichnet.

Aus „<div #text-header>“ wird im Seitenquelltext: „<div id="text-header">“.

Auch hier gilt, dass die ID-Bezeichner gültig sein müssen. Hierfür wird ein (recht einfacher) Check durchgeführt und wenn die ID nicht gültig ist, wird das Attribut nicht erzeugt.

Das „lang“-Attribut dient dazu, einen Teil der Seite (z.B. ein Wort oder eine Phrase) zu markieren, welche in einer anderen Sprache vorliegt, als der umgebende Text. In der Syntax für dieses Plugin wird der Doppelpunkt („:“) gebraucht, um Sprachattribute zu kennzeichnen.

Zum Beispiel ist auf dieser Seite der Ausdruck „ad hoc“ lateinisch und daher wie folgt ausgezeichnet: „<i :la>ad hoc</i>“. Im Seitenquellcode wird daraus: „<i lang="la">ad hoc</i>“

Auch für die Sprachkennzeichner gibt es eine Plausibilitätsprüfung. Diese ist aber flexibel genug, um praktisch alle üblichen (und die meisten unüblichen!) BCP-47 Codes abzudecken, einschließlich Regionalsprachen, Dialekte, Transliterationen und vieles weitere.

Für Sprachen, die üblicherweise von links nach rechts geschrieben werden (z.B. Arabisch oder Hebräisch) wird außerdem das „dir“-Attribut mit dem Wert „ltr“ (vom Englischen „left-to-right“) gesetzt. Dies gilt nicht, wenn die Sprache z.B. in Lateinischer Transkription geschrieben wird (siehe unten), das kann aber nicht alle Fälle abgecken, in denen die Textrichtung anders ist als erwartet (z.B. können bestimmte kurdische Dialekte sowohl von rechts nach links, als auch in umgekehrter Richtung geschrieben werden).

In diesen Fällen ist es möglich, das erweiterte Attribut „[dir="…"]“ (siehe unten) zu benutzen, um die Textrichtung unabhängig vom Sprachattribut festzulegen. Eine solche Festlegung überschreibt immer die Textrichtung der Sprache.

Einige Beispiele mit Sprachkennzeichnern für häufig gebrauchte Situationen sind in der folgenden Tabelle aufgeführt:

Das „title“-Attribut erlaubt es, einen Text anzugeben, der als sog. „Tool-tipp“ angezeigt wird, wenn der Besucher den Mauszeiger über einem Element für einen Moment still hält. Dieser Text ist auch für Screenreader wichtig, da er zusätzlich oder anstelle des Elementtextes vorgelesen werden kann.

Mit Ad-Hoc HTML wird jeder Text, der in doppelten Anführungsstrichen steht, als „title“-Attribut umgesetzt. Zum Beispiel: „<abbr "Drei-Buchstaben Abkürzung">DBA</abbr>“ wird zu „<abbr title="Drei-Buchstaben Abkürzung">DBA</abbr>“.

Dies ist das einzige Attribut, welches auch Leerzeichen unterstützt. Alles was in den Anführungsstrichen steht, wird direkt in den Seiten-Quelltext übernommen.

Alle anderen Attribute müssen mit der „erweiterten“-Syntax eingefügt werden. Diese besteht darin, Attributnamen und -wert, durch ein Gleichheitszeichen getrennt in eckige Klammern zu setzen. Anders als bei HTML-Attributen wird der Wert (auf der rechten Seite) ohne Anführungszeichen angegeben und kann auch keine Leerzeichen enthalten. Zum Beispiel: „<time [datetime=2024-01-01]>Neujahr</time>“

In einigen Fällen sind auch „leere“ Attribute erlaubt, also solche ohne Wert. Zum Beispiel: „<span [hidden]>…“

Die erlaubten Attribute sind stark eingeschränkt und wo möglich werden die Werte auch einer Plausibilitätsprüfung unterzogen, sodass in vielen Fällen ausdrücklich nur erlaubte (laut Spezifikation) Attributwerte umgesetzt werden.

Die folgenden Attribute sind für alle Elemente erlaubt:

• „[dir=…]“ (Direction) – dient dazu, die Textrichtung zu spezifizieren. Dieses Attribut überschreibt eine eventuell vom „:lang“-Attribut implizierte Textrichtung. Erlaubte Werte sind: rtl (right-to-left), ltr (left-to-right), sowie auto.

• „[hidden]“ (Hidden) – Kennzeichnet ein Element als „vorübergehend versteckt“. Ein solches Element wird vom Browser nicht angezeigt. Dieses Attribut kann entweder leer (ohne Wert) benutzt werden, oder die Werte hidden bzw. until-found haben. Alle anderen Werte werden verworfen.

• „[tabindex=…]“ (Tab Index) – Beschreibt das Verhalten des Elementes wenn der Benutzer mittels der Tab-Taste auf der Seite navigiert. Es wird empfohlen, nur die Werte „0“ (Standardverhalten) oder „-1“ (kein Tab-Ziel) zu verwenden, aber jeder Ganzzahlwert ist zulässig.

• „[is=…]“ (Custom element) Erlaubt es, eine benutzerdefinierte Elementdefinition zuzuweisen. Mehr zu diesem Thema unter: Using custom elements.

• „[style=…]“ (Inline Style) Erlaubt es inline-CSS einzufügen. Dieses Attribut muss zuerst in den Einstellungen aktiviert werden. Es wird vor allem dadurch eingeschränkt, dass keine Leerzeichen erlaubt sind. Das folgende Beispiel funktioniert jedoch: „[style=color:red;text-decoration:underline]“.

• „[data-*=…]“ (Custom data) Jedes Attribut, das mit „data-“ anfängt, dient der Datenspeicherung und wird unterstützt.

• „[itemscope]“, „[itemid=…]“, „[itemprop=…]“, „[itemref=…]“ und „[itemtype=…]“ – Mit diesen Attributen können Mikroformate in den HTML-Code eingefügt werden.

Darüber hinaus gibt es Attribute, die nur in bestimmten Elementen erlaubt sind:

• „[open]“ – Leeres Attribut, das nur in <details>-Elementen erlaubt ist. Wenn angegeben, wird das Element als geöffnet angezeigt.

• „[datetime=…]“ – Nur gültig für <details>-Elemente; kann eine beliebige ISO 8601-Datums- oder Zeitangabe enhalten.

• „[href=…]“, „[hreflang=…]“, „[target=…]“ and „[rel=…]“ sind nur gültig in <a>-Elementen (Links).
  Hinweis: javascript:-URLs sind aus sicherheitsgründen nicht erlaubt. Diese können jedoch in den Einstellungen aktiviert werden.