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, ANSI terminal output
• Extensions: Built-in extensions for external links, TOC, heading permalinks, @mentions, autolinks, default attributes, and citations
• Extensible: Custom inline/block patterns, render events
• File support: Parse and convert files directly
• CLI tools: bin/djot (one-shot convert) and bin/djot-watch (live-reload preview server) — see CLI reference

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>

Documentation

Full documentation is available at https://php-collective.github.io/djot-php/

• Getting Started - Installation and quick start
• Why Djot? - Comparison with Markdown
• Syntax Reference - Complete Djot syntax guide
• Extensions - Built-in extensions
• API Reference - Classes and methods
• Cookbook - Customization recipes

Demo

• Interactive Playground - Try djot-php in your browser
• Sandbox - Full-featured sandbox with all options

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 Safe Mode for details and advanced configuration.

Implementations

• php-collective/symfony-djot - Symfony bundle with Twig filters, services, forms, and validation
• 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.
• djot-grammars - Syntax highlighting grammars (TextMate, highlight.js, Prism.js)