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
Extensible: Custom inline/block patterns, render events
File support: Parse and convert files directly

Example

use Djot\DjotConverter;
use Djot\Event\RenderEvent;

$converter = new DjotConverter();

// Customize link rendering
$converter->on('render.link', function (RenderEvent $event): void {
    $link = $event->getNode();
    if (str_starts_with($link->getDestination(), 'http')) {
        $link->setAttribute('target', '_blank');
    }
});

$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">link</a>.</p>
<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

Examples - Comprehensive usage examples
Syntax Reference - Complete Djot syntax guide
API Reference - Classes and methods
Converters - Markdown/BBCode to Djot conversion
Cookbook - Common customizations and recipes
Architecture - Internal design

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.

php-collective / djot

Maintainers

Details