¶ Markdown Support
¶ Overview
The Markdown Support Plugin adds full Markdown formatting capabilities to osTicket 1.18.x ticket threads. It provides a user-friendly editor interface with live preview, toolbar buttons, keyboard shortcuts, and automatic format detection for API-created tickets.
Perfect for technical support teams who need to format code snippets, create structured documentation, or prefer Markdown's simplicity over traditional WYSIWYG editors.
¶ Key Features
- ✅ Markdown Editor with Toolbar - 10+ formatting buttons (Bold, Italic, Headings, Links, Code, Lists, Quotes)
- ✅ Live Preview - Real-time rendering with 500ms debouncing
- ✅ Keyboard Shortcuts - Ctrl+B (Bold), Ctrl+I (Italic), Ctrl+K (Link), Ctrl+H (Heading)
- ✅ Format Switcher - Seamlessly switch between Text, HTML, and Markdown
- ✅ Auto-Detection - Automatically detects Markdown syntax in API-created tickets
- ✅ Mobile-Responsive - Optimized for desktop and mobile devices
- ✅ Dark Mode Support - Automatic theme detection
- ✅ XSS Protection - 2-layer security (Parsedown SafeMode + Format::sanitize)
- ✅ No Core Modifications - Uses reflection-based ThreadEntryBody extension (update-safe)
¶ Table of Contents
¶ Requirements
| Component | Version | Note |
|---|---|---|
| osTicket | 1.18.x | Required (uses ThreadEntryBody class) |
| PHP | 7.4+ | Recommended: PHP 8.1+ |
| jQuery | Any | Included in osTicket |
| Parsedown | 1.7+ | Bundled with plugin |
¶ Installation
¶ Step 1: Download Plugin
Choose one of the following methods:
¶ Method 1: ZIP Download (Recommended)
- Visit GitHub Releases
- Download the latest
osticket-markdown-support-vX.X.X.zip - Extract the ZIP file
- Upload the
markdown-supportfolder to/include/plugins/on your osTicket server
¶ Method 2: Git Clone
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-markdown-support.git markdown-support
¶ Step 2: Set Permissions
chmod 755 /path/to/osticket/include/plugins/markdown-support
chmod 644 /path/to/osticket/include/plugins/markdown-support/*.php
¶ Step 3: Enable Plugin
- Login to osTicket Admin Panel
- Navigate to: Admin Panel → Manage → Plugins
- Find "Markdown Support" in the plugin list
- Click "Enable"
The plugin automatically configures static asset access by updating /include/.htaccess.
¶ Step 4: Configure (Optional)
- Click "Configure" next to "Markdown Support"
- Adjust settings as needed (see Configuration)
¶ Configuration
¶ Available Settings
| Setting | Description | Default | Use When |
|---|---|---|---|
| Enable Markdown Support | Globally enable/disable Markdown | ✅ On | You want to temporarily disable Markdown |
| Default Thread Entry Format | Default format for new entries | Markdown | You want Text or HTML as default |
| Allow Format Switching | Users can switch between formats | ✅ On | You want to lock format |
| Auto-Convert Markdown Syntax | Auto-detect Markdown patterns | ❌ Off | You create tickets via API without format parameter |
| Show Live Preview | Display real-time preview pane | ✅ On | Preview causes performance issues |
| Show Markdown Toolbar | Show formatting buttons | ✅ On | Users are Markdown experts |
¶ Recommended Settings
For Technical Teams:
- Default Format: Markdown
- Allow Format Switching: ✅ On
- Auto-Convert Markdown Syntax: ❌ Off (use explicit
formatparameter in API) - Show Live Preview: ✅ On
- Show Toolbar: ✅ On
For API-Heavy Workflows:
- Default Format: Text or Markdown
- Auto-Convert Markdown Syntax: ✅ On (if you can't modify API calls)
For Mixed Teams (Markdown + HTML users):
- Default Format: HTML
- Allow Format Switching: ✅ On
- Show Toolbar: ✅ On
¶ Usage
¶ Toolbar Buttons
The Markdown toolbar provides quick access to common formatting:
| Button | Markdown Syntax | Keyboard Shortcut | Output |
|---|---|---|---|
| B | **text** |
Ctrl+B | Bold text |
| I | *text* |
Ctrl+I | Italic text |
| H | ## text |
Ctrl+H | Heading (cycles H1-H6) |
| 🔗 | [text](url) |
Ctrl+K | Hyperlink |
<> |
`code` |
- | inline code |
{ } |
```lang\ncode\n``` |
- | Code block with syntax |
| • | - item |
- | Unordered list |
| 1. | 1. item |
- | Numbered list |
| " | > quote |
- | Blockquote |
| — | --- |
- | Horizontal rule |
¶ Keyboard Shortcuts
- Ctrl+B - Bold
- Ctrl+I - Italic
- Ctrl+H - Heading (cycles through H1-H6)
- Ctrl+K - Link
- Tab - Indent (in lists)
- Shift+Tab - Outdent (in lists)
¶ Live Preview
The live preview pane updates automatically as you type (with 500ms debouncing for performance).
Layout:
- Desktop: Side-by-side editor and preview
- Tablet: Side-by-side (responsive)
- Mobile: Stacked layout with toggle button
Preview Position:
- Default: Below editor
- Configurable via plugin settings
¶ API Integration
¶ Creating Markdown Tickets via API
Use the standard osTicket API with the format parameter:
curl -X POST "https://yourdomain.com/api/tickets.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"email": "john@example.com",
"subject": "Bug Report",
"message": "## Bug Description\\n\\n**Steps to Reproduce:**\\n1. Login\\n2. Click button\\n\\n```php\\n$code = \"example\";\\n```",
"format": "markdown",
"topicId": 1
}'
¶ Format Parameter
| Value | Description | Rendering |
|---|---|---|
"markdown" |
Markdown syntax | Parsedown → HTML |
"html" |
HTML content | Sanitized HTML |
"text" |
Plain text | Escaped text |
| (omitted) | Auto-detect if enabled | Based on plugin config |
¶ Auto-Detection (Optional)
If you cannot modify your API client to send format=markdown, enable "Auto-Convert Markdown Syntax" in plugin settings.
The plugin will detect Markdown patterns:
- Headings (
#,##,###) - Bold/Italic (
**text**,*text*) - Code blocks (
```) - Lists (
-,1.) - Links (
[text](url))
Note: Auto-detection is pattern-matching, not perfect. Explicit format parameter is recommended.
¶ Troubleshooting
¶ Plugin not visible in Admin Panel
Check:
- File permissions:
chmod 755on plugin directory,chmod 644on PHP files - Plugin files are in correct location:
/include/plugins/markdown-support/ plugin.phpexists and is readable
Test:
ls -la /path/to/osticket/include/plugins/markdown-support/plugin.php
¶ JavaScript/CSS not loading (404 errors)
Cause: .htaccess not updated to allow static assets.
Fix:
- Re-enable the plugin: Admin Panel → Plugins → Disable → Enable
- Manually verify
/include/.htaccesscontains:<FilesMatch "\.(js|css|map|json|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|otf)$"> Allow from all </FilesMatch>
NGINX Users: See NGINX Configuration
¶ Markdown not rendering (shows raw Markdown)
Check:
- Format field: Verify
format="markdown"in database (ost_thread_entry) - Parsedown: Check
vendor/Parsedown.phpexists - Error log:
tail -f /path/to/osticket/include/ost-errors.log
Common Errors:
Parsedown.php not found→ Re-download plugin from releasesClass 'MarkdownThreadEntryBody' not found→ Reload page, clear opcacheThreadEntryBody class not found→ osTicket version mismatch (requires 1.18.x)
¶ Editor not appearing on "New Ticket" form
The plugin uses MutationObserver to detect dynamically loaded textareas.
Debug Steps:
- Open browser Console (F12 → Console tab)
- Look for JavaScript errors
- Check Network tab: Verify
markdown-editor.jsloads (200 OK) - Hard refresh: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac)
If still not working:
- Check jQuery is loaded (osTicket includes it by default)
- Verify no JavaScript conflicts with other plugins
¶ Format Switcher not visible
Cause: "Allow Format Switching" is disabled in plugin settings.
Fix: Admin Panel → Plugins → Configure "Markdown Support" → Enable "Allow Format Switching"
¶ Preview not updating
Check:
- "Show Live Preview" is enabled in plugin settings
- Browser console for JavaScript errors
- Clear browser cache
Performance Note: Preview updates every 500ms (debounced). If typing very fast, preview may lag slightly.
¶ Technical Details
¶ Architecture
Plugin Type: ThreadEntryBody Extension (osTicket 1.18+)
Core Mechanism:
- Plugin extends
ThreadEntryBodyclass using PHP Reflection - Registers custom
MarkdownThreadEntryBodyclass - Intercepts ticket thread rendering
- Parses Markdown → HTML using Parsedown
- Sanitizes output using osTicket's
Format::sanitize()
No Core Modifications:
- Uses osTicket's plugin architecture
- Extends classes via Reflection
- All changes are isolated to plugin code
¶ Rendering Pipeline
User Input (Markdown)
↓
Save to Database (format="markdown")
↓
Render Thread Entry
↓
MarkdownThreadEntryBody::display()
↓
Parsedown::text($markdown)
↓
Format::sanitize($html)
↓
Display to User (Safe HTML)
¶ Security
2-Layer XSS Protection:
-
Parsedown SafeMode:
$parsedown = new Parsedown(); $parsedown->setSafeMode(true); // Escapes HTML in Markdown -
osTicket Sanitization:
$html = $parsedown->text($markdown); $safeHtml = Format::sanitize($html); // osTicket's HTML purifier
Result: Malicious scripts in Markdown are escaped and cannot execute.
¶ Database Schema
No schema changes required. Uses existing ost_thread_entry table:
| Column | Type | Usage |
|---|---|---|
format |
varchar(16) | "markdown", "html", or "text" |
body |
longtext | Raw Markdown or HTML |
¶ File Structure
markdown-support/
├── plugin.php # Plugin metadata
├── config.php # Configuration form
├── class.MarkdownPlugin.php # Main plugin class
├── markdown-body.php # ThreadEntryBody extension
├── markdown-preview.php # AJAX preview endpoint
├── log-handler.php # Debug logging
├── vendor/Parsedown.php # Markdown parser (bundled)
├── css/markdown-editor.css # Editor styles
├── js/markdown-editor.js # Editor JavaScript
├── i18n/de_DE/... # German translation
└── tests/ # PHPUnit tests
¶ NGINX Configuration
Apache: Plugin automatically configures .htaccess (no action needed)
NGINX: Add to server block:
location ~* ^/include/plugins/markdown-support/(css|js)/.*\.(css|js|map)$ {
allow all;
access_log off;
expires 30d;
}
¶ Performance
Rendering Performance:
- Markdown parsing: ~1-2ms per entry (Parsedown)
- Live preview: Debounced 500ms (no performance impact)
- Cache: Not cached (Parsedown is fast enough)
Recommendations:
- For very large tickets (>10,000 chars), preview may lag slightly on slow devices
- Consider disabling preview for performance-critical deployments
¶ FAQ
¶ Can I use Markdown in ticket subjects?
No. Markdown only works in thread entries (messages, responses, notes). Ticket subjects are plain text only.
¶ Can I mix Markdown and HTML in the same ticket?
Yes! Each thread entry has its own format field. You can have:
- Entry 1:
format="markdown" - Entry 2:
format="html" - Entry 3:
format="text"
Use the format switcher to change format per entry.
¶ Does Markdown work in Canned Responses?
No (not yet). Canned Responses use osTicket's WYSIWYG editor. Markdown support for Canned Responses is planned for a future version.
¶ Does Markdown work in email notifications?
Yes. Markdown is converted to HTML before being sent via email, so recipients see formatted content.
¶ Can I disable Markdown for specific departments?
No (not built-in). Markdown is global. However, users can switch to HTML/Text format individually using the format switcher.
¶ Is syntax highlighting supported in code blocks?
Not by default. Parsedown generates <pre><code> blocks without syntax highlighting. You can add syntax highlighting by:
- Including a library like Prism.js or Highlight.js
- Adding custom JavaScript to highlight code blocks after rendering
Example (Prism.js):
document.querySelectorAll('pre code').forEach((block) => {
Prism.highlightElement(block);
});
¶ Can I customize the toolbar buttons?
Not via UI. The toolbar is hard-coded in js/markdown-editor.js. To customize:
- Edit
js/markdown-editor.js - Modify the
toolbararray increateMarkdownToolbar() - Clear browser cache after changes
¶ Does the plugin work with osTicket 1.17 or earlier?
No. This plugin requires osTicket 1.18.x because it uses the ThreadEntryBody class introduced in 1.18.
For osTicket 1.17, you would need to:
- Modify the plugin to hook into older rendering mechanisms
- This is not officially supported
¶ Can I use this plugin with the API Endpoints Plugin?
Yes! The plugins work together seamlessly. Use format=markdown in the API Endpoints Plugin's CREATE/UPDATE endpoints.
¶ How do I migrate existing tickets to Markdown?
Manually: Edit each thread entry and switch to Markdown format using the format switcher.
Bulk Migration (Advanced):
-- Convert all "text" entries to "markdown" (example only, test first!)
UPDATE ost_thread_entry
SET format = 'markdown'
WHERE format = 'text' OR format IS NULL;
Warning: This converts ALL entries. Test on a staging server first!
¶ Does the plugin support RTL languages?
The plugin itself is language-neutral. The Markdown editor will work with RTL languages (Arabic, Hebrew), but text direction must be configured in osTicket core, not the plugin.
¶ Can I use custom Parsedown extensions?
Not directly. The plugin uses vanilla Parsedown with SafeMode enabled. To add custom extensions:
- Edit
markdown-body.php - Replace
new Parsedown()with your custom Parsedown instance - Example:
$parsedown = new ParsedownExtra(); // Use ParsedownExtra
¶ 📄 License
This plugin is released under the GNU General Public License v2, compatible with osTicket core.
See LICENSE for details.
¶ 💬 Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-markdown-support/issues
When reporting issues, please include:
- osTicket version (Admin Panel → Settings → About)
- PHP version (
php -v) - Plugin version
- Browser console errors (F12 → Console)
- Steps to reproduce
¶ 🤝 Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
¶ Changelog
See CHANGELOG.md for version history.