¶ Markdown Support
¶ Inhaltsverzeichnis
- Systemanforderungen
- Installation
- Konfigurations-Optionen
- Nutzung
- API-Integration
- Fehlerbehebung
- Technische Details
- FAQ
¶ Überblick
Fügt Markdown-Formatierungs-Unterstützung zu osTicket 1.18.x Ticket-Threads hinzu mit benutzerfreundlicher Editor-Oberfläche, Live-Vorschau und automatischer Format-Erkennung.
Perfekt für Support-Teams, die die Einfachheit von Markdown gegenüber HTML-WYSIWYG-Editoren bevorzugen, besonders für technische Dokumentation, Code-Snippets und API-Integrationen.
¶ Hauptfunktionen
- ✅ Markdown-Editor mit Toolbar - 10+ Formatierungs-Buttons (Fett, Kursiv, Überschriften, Links, Code, Listen, Zitate)
- ✅ Live-Vorschau - Echtzeit-Rendering während des Tippens
- ✅ Tastatur-Shortcuts - Strg+B (Fett), Strg+I (Kursiv), Strg+K (Link), Strg+H (Überschrift)
- ✅ Format-Umschalter - Wechsel zwischen Text-, HTML- und Markdown-Formaten
- ✅ Auto-Erkennung - Erkennt automatisch Markdown-Syntax in per API erstellten Tickets
- ✅ Mobile-Responsive - Optimiert für Desktop und Mobile
- ✅ Dark-Mode-Unterstützung - Automatische Theme-Erkennung
- ✅ XSS-Schutz - 2-Schicht-Sicherheit (Parsedown SafeMode + Format::sanitize)
- ✅ Keine Core-Modifikationen - Nutzt Reflection-basierte Extension (Update-sicher)
¶ Anwendungsfälle
- Technische Support-Teams - Markdown für Code-Blöcke und Syntax-Highlighting verwenden
- Interne Notizen - Schnelle Formatierung ohne WYSIWYG-Komplexität
- API-Integrationen - Auto-Erkennung von Markdown in per API erstellten Tickets
- Dokumentation - Strukturierte Antworten mit Überschriften und Listen erstellen
- Copy-Paste von GitHub - Markdown-Inhalte lassen sich nahtlos einfügen
¶ Systemanforderungen
| Anforderung | Version | Hinweise |
|---|---|---|
| osTicket | 1.18.x | Plugin erweitert ThreadEntryBody-Klasse |
| PHP | 7.4+ | Empfohlen: PHP 8.1+ für beste Performance |
| jQuery | Beliebig | In osTicket standardmäßig enthalten |
| Parsedown | 1.7.4 | Im Plugin enthalten (vendor/) |
¶ Installation
¶ Schritt 1: Plugin-Dateien installieren
¶ Methode 1: ZIP-Download (Empfohlen)
- Lade das neueste Release von Releases herunter
- Entpacke die ZIP-Datei
- Lade den
markdown-support-Ordner nach/include/plugins/auf deinem osTicket-Server hoch
Finaler Pfad: /pfad/zu/osticket/include/plugins/markdown-support/
¶ Methode 2: Git Repository
cd /pfad/zu/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-markdown-support.git
¶ Schritt 2: Plugin in osTicket aktivieren
- Melde dich im osTicket Admin Panel an
- Navigiere zu: Admin Panel → Verwalten → Plugins
- Finde "Markdown Support" in der Liste
- Klicke auf "Aktivieren"
Das Plugin konfiguriert automatisch den Static-Asset-Zugriff (.htaccess-Update).
¶ Schritt 3: Plugin konfigurieren (Optional)
- Klicke auf "Konfigurieren" neben "Markdown Support"
- Passe Einstellungen an:
- ✅ Markdown-Unterstützung aktivieren - Markdown global aktivieren/deaktivieren
- 📝 Standard-Format - Standard-Format für neue Einträge festlegen (Text/HTML/Markdown)
- 🔄 Format-Wechsel erlauben - Nutzern erlauben, zwischen Formaten zu wechseln
- 🤖 Markdown-Syntax auto-konvertieren - Automatisch Markdown-Muster in API-Tickets erkennen
- 👁️ Live-Vorschau anzeigen - Live-Vorschau-Bereich aktivieren/deaktivieren
- 🛠️ Toolbar anzeigen - Formatierungs-Toolbar zeigen/verstecken
¶ Konfigurations-Optionen
| Einstellung | Beschreibung | Standard |
|---|---|---|
| Markdown-Unterstützung aktivieren | Markdown-Formatierung global aktivieren/deaktivieren | ✅ An |
| Standard Thread-Entry-Format | Standard-Format für neue Einträge | Markdown |
| Format-Wechsel erlauben | Nutzer können zwischen Text/HTML/Markdown wechseln | ✅ An |
| Markdown-Syntax auto-konvertieren | Automatisch Markdown-Muster erkennen | ❌ Aus |
| Live-Vorschau anzeigen | Echtzeit-Vorschau-Bereich anzeigen | ✅ An |
| Markdown-Toolbar anzeigen | Formatierungs-Buttons anzeigen | ✅ An |
Tipp: Aktiviere "Markdown-Syntax auto-konvertieren", wenn du Tickets per API mit Markdown-Inhalten erstellst, aber keinen expliziten Format-Parameter setzt.
¶ Nutzung
¶ Toolbar-Buttons
| Button | Markdown | Shortcut | Beschreibung |
|---|---|---|---|
| B | **text** |
Strg+B | Text fett |
| I | *text* |
Strg+I | Text kursiv |
| H | ## text |
Strg+H | Überschrift (wechselt H1-H6) |
| 🔗 | [text](url) |
Strg+K | Link einfügen |
<> |
`code` |
- | Inline-Code |
{ } |
```lang |
- | Code-Block |
| • | - item |
- | Unsortierte Liste |
| 1. | 1. item |
- | Sortierte Liste |
| " | > quote |
- | Blockzitat |
| — | --- |
- | Horizontale Linie |
¶ Live-Vorschau
Der Live-Vorschau-Bereich zeigt Echtzeit-Rendering deines Markdown-Inhalts. Aktualisiert automatisch mit 500ms Debouncing für optimale Performance.
- Desktop: Nebeneinander Editor und Vorschau
- Mobile: Gestapeltes Layout mit Toggle-Button
¶ Tastatur-Shortcuts
| Shortcut | Aktion |
|---|---|
| Strg+B | Text fett machen |
| Strg+I | Text kursiv machen |
| Strg+K | Link einfügen |
| Strg+H | Überschrift einfügen (wechselt H1-H6) |
| Tab | Code einrücken |
¶ Markdown-Syntax-Beispiele
¶ Überschriften
# Überschrift 1
## Überschrift 2
### Überschrift 3
¶ Text-Formatierung
**Fetter Text**
*Kursiver Text*
~~Durchgestrichen~~
`Inline-Code`
¶ Listen
- Unsortierte Liste
- Element 2
- Unterelement
1. Sortierte Liste
2. Element 2
¶ Links & Bilder
[Link-Text](https://example.com)
¶ Code-Blöcke
```php
<?php
echo \"Hallo Welt!\";
?>
```
¶ Zitate
> Dies ist ein Zitat
> Über mehrere Zeilen
¶ Tabellen
| Spalte 1 | Spalte 2 |
|----------|----------|
| Wert 1 | Wert 2 |
¶ API-Integration
¶ Format-Parameter in API-Requests
Beim Erstellen von Tickets über die osTicket API kannst du das format-Feld verwenden, um Markdown anzugeben:
POST /api/tickets.json
{
\"name\": \"Max Mustermann\",
\"email\": \"max@example.com\",
\"subject\": \"Ticket mit Markdown\",
\"message\": \"## Problem\\\\n\\\\nDer Server antwortet **nicht**.\\\\n\\\\n```bash\\\\nping server.example.com\\\\n```\",
\"format\": \"markdown\"
}
¶ Auto-Erkennung aktivieren
Falls deine API-Integration kein format-Feld sendet, aber Markdown-Syntax enthält:
- Admin Panel → Plugins → Markdown Support → Konfigurieren
- Aktiviere "Markdown-Syntax auto-konvertieren"
- Das Plugin erkennt automatisch Markdown-Muster wie:
**fett**,*kursiv*# Überschriften`code`[Links](url)
Erkennungs-Schwellenwert: Mindestens 2 Markdown-Muster pro 100 Zeichen
¶ Unterstützte Format-Werte
| Format-Wert | Beschreibung |
|---|---|
text |
Plain-Text (keine Formatierung) |
html |
HTML-WYSIWYG-Editor |
markdown |
Markdown-Editor mit Live-Vorschau |
¶ Fehlerbehebung
¶ Plugin nicht sichtbar im Admin Panel
Symptome:
- Plugin erscheint nicht in Admin Panel → Plugins
Lösung:
Datei-Berechtigungen prüfen:
chmod 755 /pfad/zu/osticket/include/plugins/markdown-support
chmod 644 /pfad/zu/osticket/include/plugins/markdown-support/*.php
¶ JavaScript/CSS lädt nicht
Symptome:
- Toolbar erscheint nicht
- Live-Vorschau funktioniert nicht
- Browser-Konsole zeigt 403-Fehler für
.js/.css-Dateien
Lösung:
Das Plugin sollte automatisch /include/.htaccess aktualisieren. Falls Assets nicht laden:
- Plugin erneut aktivieren (Deaktivieren → Aktivieren)
- Manuell
/include/.htaccessprüfen - sollte enthalten:<FilesMatch \"\\.(js|css|map|json|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|otf)$\"> Allow from all </FilesMatch> - Falls .htaccess fehlt, erstelle sie manuell im
/include/-Verzeichnis
¶ Markdown rendert nicht
Symptome:
- Markdown-Syntax wird als roher Text angezeigt
- Keine Formatierung im Ticket
Prüfen:
-
Error-Log überprüfen:
tail -f /pfad/zu/osticket/include/ost-errors.log -
Häufige Probleme:
Parsedown.php not found→ Plugin erneut von Releases herunterladenThreadEntryBody class not found→ osTicket-Versions-Mismatch (benötigt 1.18.x)Class 'ReflectionClass' not found→ PHP-Reflection-Extension fehlt
-
Plugin-Konfiguration prüfen:
- Admin Panel → Plugins → Markdown Support → Konfigurieren
- "Markdown-Unterstützung aktivieren" muss ✅ sein
¶ Editor erscheint nicht bei "Neues Ticket"-Formular
Symptome:
- Standard-Textarea wird angezeigt, kein Markdown-Editor
- Toolbar fehlt
Lösung:
Das Plugin nutzt einen MutationObserver, um dynamisch geladene Textareas zu erkennen. Falls der Editor nicht erscheint:
- Browser-Konsole auf JavaScript-Fehler prüfen (F12 → Console)
- Assets laden verifizieren (Network-Tab sollte 200 OK für CSS/JS zeigen)
- Seite hart neu laden (Strg+Umschalt+R)
- jQuery-Verfügbarkeit prüfen:
// In Browser-Konsole: typeof jQuery // Sollte \"function\" zurückgeben
¶ Live-Vorschau zeigt falsche Formatierung
Symptome:
- Vorschau unterscheidet sich vom finalen Ticket
- HTML-Entities werden falsch angezeigt
Erklärung:
Die Live-Vorschau nutzt JavaScript-Parsedown (Marked.js) für Performance, während das finale Rendering PHP-Parsedown nutzt. Kleine Unterschiede können auftreten bei:
- Komplexen HTML-Entities
- Benutzerdefinierten Parsedown-Erweiterungen
- Edge-Cases in Markdown-Syntax
Lösung:
Das finale Ticket ist maßgeblich. Die Live-Vorschau ist ein Hilfsmittel, garantiert aber keine 100%-ige Übereinstimmung.
¶ XSS-Warnung in Logs
Symptome:
- Error-Log zeigt XSS-Warnungen
- Bestimmte HTML-Tags werden entfernt
Erklärung:
Das Plugin nutzt 2-Schicht-Sicherheit:
- Parsedown SafeMode - Verhindert Inline-HTML
- Format::sanitize - osTickets Standard-XSS-Filter
Verhalten:
<script>wird entfernt<iframe>wird entferntonclick=und andere Event-Handler werden entfernt
Wenn HTML benötigt wird:
- Nutze den HTML-Format-Editor statt Markdown
- Parsedown SafeMode kann NICHT deaktiviert werden (Sicherheits-Feature)
¶ Format-Umschalter funktioniert nicht
Symptome:
- Dropdown zeigt nur "Text" und "HTML", kein "Markdown"
- Kann nicht zu Markdown wechseln
Prüfen:
-
Plugin-Konfiguration:
- Admin Panel → Plugins → Markdown Support → Konfigurieren
- "Format-Wechsel erlauben" muss ✅ sein
- "Markdown-Unterstützung aktivieren" muss ✅ sein
-
JavaScript-Initialisierung:
- Browser-Konsole öffnen (F12)
- Nach
MarkdownEditor initializedsuchen - Falls fehlend: Assets laden nicht korrekt
¶ Markdown in bestehenden Tickets konvertieren
Szenario:
- Du hast bereits Tickets mit Plain-Text
- Möchtest diese nachträglich als Markdown formatieren
Lösung:
Das Plugin ändert keine bestehenden Tickets. Um alte Tickets zu konvertieren:
- Manuell: Ticket öffnen → Antworten → Format auf "Markdown" setzen
- Bulk-Migration: SQL-Query (VORSICHTIG!)
-- Nur als Beispiel - BACKUP ERSTELLEN! UPDATE ost_thread_entry SET format = 'markdown' WHERE format = 'text' AND body LIKE '%**%' -- Nur Einträge mit Markdown-Syntax
¶ Technische Details
¶ Architektur
Plugin-Struktur:
markdown-support/
├── plugin.php # Plugin-Metadaten
├── class.MarkdownPlugin.php # Haupt-Plugin-Klasse
├── config.php # Plugin-Konfiguration
├── class.MarkdownThreadEntryBody.php # ThreadEntryBody-Extension
├── vendor/
│ └── Parsedown.php # Parsedown-Library (1.7.4)
├── assets/
│ ├── css/
│ │ └── markdown-editor.css # Editor-Styles
│ └── js/
│ ├── markdown-editor.js # Editor-Initialisierung
│ └── marked.min.js # JavaScript-Markdown-Parser
└── tests/
└── Unit/ # PHPUnit-Tests
Reflection-Based Extension:
Das Plugin erweitert osTickets ThreadEntryBody-Klasse via PHP Reflection, um neue Format-Typen hinzuzufügen:
// class.MarkdownPlugin.php
$reflection = new ReflectionClass('ThreadEntryBody');
$property = $reflection->getProperty('formats');
$property->setAccessible(true);
$formats = $property->getValue(null);
$formats['markdown'] = 'Markdown';
$property->setValue(null, $formats);
Vorteile:
- ✅ Keine Core-Dateien-Modifikationen
- ✅ Update-sicher
- ✅ Plugin kann jederzeit deaktiviert werden
¶ Sicherheits-Features
-
Parsedown SafeMode:
- Verhindert Inline-HTML in Markdown
- Blockiert
<script>,<iframe>,<object>etc. - Standard für alle Markdown-Rendering
-
Format::sanitize:
- osTickets Standard-XSS-Filter
- Entfernt gefährliche Attribute (
onclick,onerror) - Whitelist-basierte HTML-Tag-Filterung
-
CSRF-Schutz:
- Plugin nutzt osTickets CSRF-Token-System
- Alle Admin-Aktionen benötigen gültiges Token
-
Input-Validierung:
- Alle Konfigurationswerte werden validiert
- Checkbox-Werte als Boolean gecastet
- String-Werte escaped
¶ Performance-Optimierungen
-
JavaScript-Debouncing:
- Live-Vorschau aktualisiert mit 500ms Delay
- Verhindert excessive Re-Rendering
-
Lazy-Loading:
- Marked.js wird nur geladen, wenn Markdown-Editor aktiv
- CSS wird nur auf relevanten Seiten geladen
-
MutationObserver:
- Effiziente Detektion dynamisch hinzugefügter Textareas
- Einmalige Initialisierung pro Textarea
-
Caching:
- Parsedown-Instanz wird wiederverwendet
- Static-Assets profitieren von Browser-Caching
¶ Parsedown-Version
Aktuell: Parsedown 1.7.4 (im Plugin enthalten)
Warum nicht Parsedown 2.0?
- Parsedown 2.0 erfordert PHP 7.4+ mit Composer
- Plugin enthält 1.7.4 für maximale Kompatibilität
- Version 1.7.4 ist stabil und sicher
Update-Pfad:
# Falls du auf Parsedown 2.0 upgraden möchtest (optional):
cd /pfad/zu/osticket/include/plugins/markdown-support
composer require erusev/parsedown:^2.0
# Dann: class.MarkdownThreadEntryBody.php anpassen
¶ FAQ
¶ Allgemeine Fragen
F: Funktioniert Markdown in Client-Portal?
A: Ja! Markdown-formatierte Ticket-Antworten werden korrekt im Client-Portal gerendert. Clients können jedoch nicht im Markdown-Format schreiben (nur Staff).
F: Kann ich Markdown als Standard-Format für alle neuen Tickets setzen?
A: Ja, in der Plugin-Konfiguration:
- Admin Panel → Plugins → Markdown Support → Konfigurieren
- "Standard Thread-Entry-Format" → Markdown auswählen
F: Was passiert, wenn ich das Plugin deaktiviere?
A: Bestehende Markdown-formatierte Einträge werden als roher Markdown-Text angezeigt (nicht gerendert). Keine Daten gehen verloren - bei erneutem Aktivieren werden sie wieder korrekt gerendert.
F: Kann ich Markdown und HTML im gleichen Ticket mischen?
A: Ja, jede Ticket-Antwort kann ihr eigenes Format haben. Du kannst z.B. die erste Antwort in HTML und die zweite in Markdown schreiben.
¶ Markdown-Syntax
F: Unterstützt das Plugin GitHub-Flavored Markdown (GFM)?
A: Teilweise. Das Plugin nutzt Standard-Parsedown, das folgende GFM-Features unterstützt:
- ✅ Fenced Code Blocks (
```) - ✅ Tabellen
- ✅ Autolinks
- ❌ Task-Listen (
- [ ]) - nicht unterstützt - ❌ Emoji-Shortcuts (
:smile:) - nicht unterstützt
F: Wie füge ich Syntax-Highlighting zu Code-Blöcken hinzu?
A: Parsedown unterstützt Sprach-Identifikatoren, aber kein automatisches Syntax-Highlighting. Für Highlighting:
- Füge ein JavaScript-Highlighting-Plugin hinzu (z.B. Prism.js, Highlight.js)
- Integriere es in osTickets Template
- Parsedown wird Code-Blöcke mit
class=\"language-php\"markieren
F: Kann ich HTML innerhalb von Markdown verwenden?
A: Nein, aus Sicherheitsgründen. Parsedown läuft im SafeMode, der Inline-HTML blockiert. Falls HTML benötigt wird, nutze den HTML-Format-Editor.
F: Wie erstelle ich mehrzeilige Code-Blöcke?
A: Nutze Triple-Backticks mit optionalem Sprach-Identifier:
```php
<?php
echo \"Hallo Welt!\";
?>
```
¶ Integration & API
F: Wie sende ich Markdown-formatierte Tickets per API?
A: Setze das format-Feld auf \"markdown\":
curl -X POST https://osticket.example.com/api/tickets.json \\
-H \"X-API-Key: YOUR_API_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{
\"name\": \"API User\",
\"email\": \"api@example.com\",
\"subject\": \"Ticket mit Markdown\",
\"message\": \"## Problem\\\\n\\\\n**Server** ist offline.\",
\"format\": \"markdown\"
}'
F: Was passiert, wenn ich kein Format-Feld sende?
A: Das Plugin nutzt das konfigurierte Standard-Format. Falls "Markdown-Syntax auto-konvertieren" aktiviert ist, wird Markdown-Syntax automatisch erkannt.
F: Kann ich bestehende Tickets per API auf Markdown umstellen?
A: osTicket API bietet kein direktes Update von Thread-Entry-Formaten. Du müsstest SQL direkt nutzen:
UPDATE ost_thread_entry
SET format = 'markdown'
WHERE thread_id = 123 AND id = 456;
¶ Kompatibilität
F: Funktioniert das mit osTicket 1.17 oder älter?
A: Nein. Das Plugin benötigt osTicket 1.18.x für die ThreadEntryBody-Klassen-Struktur. ältere Versionen haben eine andere Thread-Entry-Architektur.
F: Ist es kompatibel mit anderen Plugins?
A: Meistens ja, aber Konflikte können auftreten mit:
- Anderen Editor-Plugins (WYSIWYG-Erweiterungen)
- Plugins, die
ThreadEntryBodymodifizieren - JavaScript-intensive Plugins, die jQuery überschreiben
F: Funktioniert es mit benutzerdefinierten osTicket-Themes?
A: Ja, das Plugin nutzt osTickets Standard-CSS-Klassen. Das Editor-CSS ist minimalistisch und sollte mit den meisten Themes funktionieren.
F: Ist es kompatibel mit PHP 8.x?
A: Ja! Das Plugin ist mit PHP 7.4, 8.0, 8.1, 8.2 und 8.3 getestet. CI-Pipeline testet alle Versionen.
¶ Performance & Skalierung
F: Beeinträchtigt das Plugin die Ticket-Lade-Performance?
A: Minimal. Markdown-Parsing ist sehr schnell (~0.1ms pro Eintrag). Bei Tickets mit 100+ Antworten könnte ein kleiner Performance-Hit bemerkbar sein, aber vernachlässigbar.
F: Wie groß können Markdown-Einträge sein?
A: Parsedown hat keine Größenbeschränkung. osTickets Datenbank-Limit für ost_thread_entry.body ist MEDIUMTEXT (16 MB).
F: Wird Markdown-Rendering gecacht?
A: Nein, aktuell kein Caching. Jedes Mal, wenn ein Ticket geladen wird, wird Markdown neu gerendert. Für Hochlast-Systeme könnte ein Caching-Layer hinzugefügt werden.
¶ 📄 Lizenz
Dieses Plugin wird unter der GNU General Public License v2 veröffentlicht, kompatibel mit osTicket Core.
Details siehe LICENSE.
¶ 💬 Support
Für Fragen oder Probleme erstelle bitte ein Issue auf GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-markdown-support/issues
Beim Melden von Problemen bitte angeben:
- osTicket-Version (Admin Panel → Einstellungen → Über)
- PHP-Version (
php -v) - Plugin-Version
- Browser-Konsolen-Fehler (F12 → Console)
- Schritte zur Reproduktion
¶ 🤝 Mitwirken
Entwickelt von Markus Michalski
Beiträge willkommen!
- Repository forken
- Feature-Branch erstellen
- Pull Request einreichen
¶ Changelog
Siehe CHANGELOG.md für Versionshistorie.