Deutsche Version

Back to overview

Markdown Support: Technical Details

Plugin metadata

Startup flow

graph TD
    A["bootstrap()"] --> B["Load configuration into ConfigCache"]
    B --> C["Check version and copy preview endpoint"]
    C --> D{"Enable Markdown Support on?"}
    D -->|"No"| E["End"]
    D -->|"Yes"| F["Extend ThreadEntryBody::types with markdown"]
    F --> G["Load MarkdownThreadEntryBody, patch class.thread.php"]
    G --> H["Pre-process POST for email"]
    H --> I["Connect signals object.view and threadentry.created"]
    I --> J["Output buffer for editor pages"]

Core intervention

The plugin needs two interventions in osTicket:

• Via reflection: It adds the value markdown to the static property ThreadEntryBody::$types. No file change is needed for this.
• Via file patch: In include/class.thread.php it inserts the branch case 'markdown': return new MarkdownThreadEntryBody(...) after the case 'html': branch of ThreadEntryBody::fromFormattedText(). If it cannot find the pattern (a different osTicket version), it logs Unable to apply patch - pattern not found to the PHP error log and does not patch.

If the file already contains a case 'markdown':, the plugin does nothing. Before patching, it copies the file to include/class.thread.php.markdown-backup if no backup exists yet. On deactivation it restores the file from this backup and deletes it. If the backup is missing, it restores nothing. An existing backup is not overwritten (see Installation, section Updating osTicket).

Rendering

MarkdownThreadEntryBody extends ThreadEntryBody with the type markdown and renders in display():

1. Parsedown with setSafeMode(true) converts Markdown to HTML.
2. osTicket's Format::sanitize() cleans the result.
3. In pdf mode the plugin replaces img tags with an http(s) source with the text [Image]. In email mode the HTML stays unchanged.

Search indexing (getSearchable()) converts the rendered HTML to text with Format::html2text().

Email handling

osTicket uses the raw POST text for emails. The Markdown editor sends plain text, so emails would otherwise show Markdown syntax. The plugin proceeds as follows:

1. On a POST with format=markdown it saves the fields response, note and message, renders them to HTML with MarkdownThreadEntryBody and sets format to html for osTicket.
2. osTicket creates the entry as HTML and sends the email with the rendered text.
3. The handler for threadentry.created remembers the ID of the entry.
4. A shutdown function writes the original Markdown and format = 'markdown' back to THREAD_ENTRY_TABLE via SQL at the end of the request.

In addition, the handler corrects the format via threadentry.created when the request carries a valid format (see API integration).

Editor assets

• Signal object.view: For a Ticket the plugin outputs the configuration block window.osTicketMarkdownConfig (defaultFormat, allowFormatSwitch, showToolbar, previewApiUrl), the stylesheet and the script js/markdown-editor.js. The files get ?v=<installed version> as a cache parameter.
• Output buffer: On non-AJAX pages with the script name tickets.php or ticket.php (and ajax.php URLs containing ticket) the plugin also starts an output buffer that inserts the same assets before </head>. A check for window.osTicketMarkdownConfig prevents double insertion.

Preview endpoint

markdown-preview.php is copied to api/markdown-preview.php on activation (and on every start if the file differs), because include/ is blocked by .htaccess. The endpoint:

• accepts only POST with JSON {"markdown": "..."} and answers with {"success": true, "html": "..."},
• renders with Parsedown in SafeMode and then filters javascript: and data: values in href/src, on* attributes, style with expression() and script tags,
• does not load osTicket and therefore checks neither login nor CSRF token,
• does not limit the size of the markdown field,
• looks for Parsedown at vendor/autoload.php next to the file or at ../include/plugins/markdown-support/vendor/autoload.php.

The endpoint exists at two paths: as api/markdown-preview.php (copied there by the plugin) and as the original in the plugin folder include/plugins/markdown-support/markdown-preview.php, which the plugin's .htaccess opens. Both paths are reachable without login, check no CSRF token, do not limit the size of the input and do not load osTicket. The editor's live preview uses only the copy in api/.

The preview does not pass through Format::sanitize(), only through its own filter. It therefore does not always show exactly the HTML that later appears in the ticket view.

Security

The class MarkdownSanitizer is included with tests but is not called in the plugin's runtime flow.

Changes to include/.htaccess

On activation the plugin inserts two blocks: a FilesMatch block that allows js, css, map, json, images and fonts, and a block for PHP files under plugins/. On deactivation it removes both blocks again. There is no automatic adjustment for NGINX.

Apache matches the rule for PHP files (<FilesMatch "^plugins/.+\.php$">) only against file names without a path, so it probably never matches. markdown-preview.php is opened by the Files directive in the plugin folder's .htaccess.

File structure

markdown-support/
├── plugin.php                 # plugin metadata
├── class.MarkdownPlugin.php   # plugin class, signals, enable/disable
├── config.php                 # MarkdownConfig with the options
├── markdown-body.php          # MarkdownThreadEntryBody
├── markdown-preview.php       # preview endpoint (a copy goes to api/)
├── MarkdownDetector.php       # Markdown syntax detection
├── .htaccess                  # allows the endpoint, blocks logs
├── src/
│   ├── Config/ConfigCache.php
│   ├── Core/CorePatcher.php
│   ├── Asset/AssetInjector.php
│   ├── Asset/AssetDeployer.php
│   ├── Http/MarkdownPostProcessor.php
│   ├── Signal/ThreadEntryHandler.php
│   └── Format/                # sanitizer and interfaces
├── css/markdown-editor.css
├── js/markdown-editor.js      # bundled from js/src/
├── i18n/de_DE/                # German translation of the configuration
└── vendor/                    # Parsedown (Composer)

The repository additionally contains tests (PHPUnit), build sources for the JavaScript and documentation. CI runs a syntax check (php -l) with PHP 7.4 to 8.3.