README

A PHP parser for Djot, a modern light markup language created by John MacFarlane (author of CommonMark/Pandoc).

Installation

composer require php-collective/djot

Quick Start

use Djot\DjotConverter;

$converter = new DjotConverter();
$html = $converter->convert('Hello *world*!');
// Output: <p>Hello <strong>world</strong>!</p>

Features

• Block elements: Headings, paragraphs, code blocks, block quotes, lists, tables, divs, definition lists, line blocks
• Inline elements: Emphasis, strong, links, images, code, superscript, subscript, highlight, insert, delete
• Advanced: Footnotes, math expressions, symbols, block attributes, raw HTML blocks, comments
• Smart typography: Curly quotes, en/em dashes, ellipsis
• Multiple renderers: HTML, plain text, Markdown output
• Extensions: Built-in extensions for external links, TOC, heading permalinks, @mentions, autolinks, default attributes
• Extensible: Custom inline/block patterns, render events
• File support: Parse and convert files directly

Example

use Djot\DjotConverter;
use Djot\Extension\ExternalLinksExtension;
use Djot\Extension\DefaultAttributesExtension;

$converter = new DjotConverter();

// Add extensions for common features
$converter
    ->addExtension(new ExternalLinksExtension())
    ->addExtension(new DefaultAttributesExtension([
        'table' => ['class' => 'table'],
    ]));

$djot = <<<'DJOT'
# Welcome

This is _emphasized_ and *strong* text with a [link](https://example.com).

| Name  | Role       |
|-------|------------|
| Alice | Developer  |
| Bob   | Designer   |

> "Djot is a light markup syntax."

```php
echo "Hello World";
DJOT;

echo $converter->convert($djot);

Output:

<h1>Welcome</h1>
<p>This is <em>emphasized</em> and <strong>strong</strong> text with a <a href="https://example.com" target="_blank" rel="noopener noreferrer">link</a>.</p>
<table class="table">
<thead>
<tr><th>Name</th><th>Role</th></tr>
</thead>
<tbody>
<tr><td>Alice</td><td>Developer</td></tr>
<tr><td>Bob</td><td>Designer</td></tr>
</tbody>
</table>
<blockquote>
<p>"Djot is a light markup syntax."</p>
</blockquote>
<pre><code class="language-php">echo "Hello World";
</code></pre>

Demo: Sandbox with live preview

https://sandbox.dereuromark.de/sandbox/djot

Documentation

• Why Djot? - Comparison with Markdown, migration guide
• Examples - Comprehensive usage examples
• Syntax Reference - Complete Djot syntax guide
• API Reference - Classes and methods
• Extensions - Built-in extensions for common features
• Profiles - Feature restriction for different contexts
• Converters - Markdown/BBCode to Djot conversion
• Cookbook - Common customizations and recipes
• Architecture - Internal design
• Enhancements - Fixes beyond the current spec
• Performance - Benchmarks and performance data

Security

When processing untrusted user input, enable safe mode for XSS protection:

$converter = new DjotConverter(safeMode: true);
$html = $converter->convert($untrustedInput);

Safe mode automatically blocks dangerous URL schemes (javascript:, etc.), strips event handler attributes (onclick, etc.), and escapes raw HTML.

See Security Considerations for details and advanced configuration.

Implementations

• php-collective/wp-djot - WordPress plugin for Djot support
• dereuromark/cakephp-markup - CakePHP integration with Djot helper and view class

See Also

• Djot - Official Djot website with syntax reference and playground
• jgm/djot - Reference implementation in JavaScript by John MacFarlane
• JetBrains IDE support - Plugin for PhpStorm, IntelliJ IDEA, WebStorm, etc.