Djot PHP: A Modern Markup Parser

What is Djot?

Djot is a lightweight markup language by the author of Commonmark, Markdown and Pandoc. It takes the best ideas from Markdown while addressing many of its ambiguities and limitations. The syntax is familiar yet more predictable, making it an excellent choice for content-heavy applications. You could call it somewhat a possible successor.

The php-collective/djot composer package brings full Djot support to PHP 8.2+, with 100% compatibility with the official djot test suite.

Use Cases

Let’s talk about common cases where such a markup language would be beneficial:

• Blog engines and CMS platforms
• Documentation systems
• Technical writing applications
• User-generated content (comments, forums) with Profile-based restrictions
• Any project requiring lightweight markup with advanced formatting
• Customizable to specific (business relevant) markup/constructs
• Secure by design

Let’s see if Djot fits these needs.

Feature Highlights

| Feature     | Status |   Notes |
|:------------|:------:|--------:|
| Left-align  | Center | Right   |

Task Lists

Native checkbox support for task lists:

- [x] Create parser
- [x] Create renderer
- [ ] World domination

Since this post is written in Djot, here’s the actual rendered output:

• Create parser
• Create renderer
• World domination

Divs with Classes

Create styled containers with the triple-colon syntax:

::: warning
This is a warning message.
:::

Renders as:

<div class="warning">
<p>This is a warning message.</p>
</div>

Live demo:

Spans with Attributes

Add classes, IDs, or custom attributes to inline content:

This is [important]{.highlight #key-point}

Code Blocks

Fenced code blocks with syntax highlighting hints:

```php
$converter = new DjotConverter();
echo $converter->convert($text);
```

> To be or not to be,
> that is the question.

^ William Shakespeare

The Markdown Elephant in the Room

Let’s be honest: Markdown has quirks. Ever spent 20 minutes debugging why your nested list won’t render correctly? Or wondered why _this_works_ but _this_doesn't_ in some parsers?

Djot was designed by someone who knows these pain points intimately – John MacFarlane literally wrote the CommonMark spec. With Djot, he started fresh with lessons learned from years of Markdown edge cases.

The result? A syntax that feels familiar but actually behaves predictably. Your users write content, not workarounds.

Why Djot Over Markdown?

• More consistent syntax – Fewer edge cases and ambiguities
• Better nesting – Clear rules for nested emphasis and containers
• Built-in features – Highlights, insertions, deletions, and spans without extensions
• Smart typography – Automatic without additional plugins
• Cleaner specification – Easier to implement correctly
• Easier to extend – AST makes adding new features straightforward
• Secure by design – Random unfenced HTML like <b>...</b> shouldn’t be treated as such blindly

Djot vs Markdown: Quick Comparison

Trailing spaces are problematic since most IDEs and editors auto-trim whitespace. Using a visible \ character is much cleaner.

Auto-HTML is also problematic for user-generated content. Djot treats everything as text by default – you must explicitly enable raw HTML (see below).

Basic Usage

Converting Djot to HTML is straightforward:

use Djot\DjotConverter;

$converter = new DjotConverter();
$html = $converter->convert($djotText);

Need XHTML output? Just pass a flag:

$converter = new DjotConverter(xhtml: true);

Advanced Usage

For more control, you can work with the AST directly:

$converter = new DjotConverter();

// Parse to AST
$document = $converter->parse($djotText);

// Manipulate the AST if needed...

// Render to HTML
$html = $converter->render($document);

Markdown compatibility modes

Note: This is specific to this library and not yet officially in the specs. Using this in your apps means, your users get the best out of both concepts, but it also means you need to clarify and document this and cannot “just” link to djot specs.

$renderer = $converter->getRenderer(); // HtmlRenderer

// Default - newline in source, invisible in browser
$renderer->setSoftBreakMode(SoftBreakMode::Newline);

// Space - same visual result, slightly smaller HTML
$renderer->setSoftBreakMode(SoftBreakMode::Space);

// Break - every source line break becomes visible <br>
$renderer->setSoftBreakMode(SoftBreakMode::Break);

$converter = new DjotConverter(significantNewlines: true);

$result = $converter->convert("Here's a list:
- Item one
- Item two");
// Output: <p>Here's a list:</p>\n<ul><li>Item one</li><li>Item two</li></ul>

// Without escaping - creates a list
$result = $converter->convert("Price:
- 10 dollars");
// Output: <p>Price:</p><ul><li>10 dollars</li></ul>

// With escaping - literal text
$result = $converter->convert("Price:
\\- 10 dollars");
// Output: <p>Price:<br>- 10 dollars</p>

Customization

use Djot\Renderer\Event\RenderEvent;

$renderer = $converter->getRenderer();

// Convert :emoji: symbols to actual emoji
$renderer->addEventListener('render.symbol', function (RenderEvent $event) {
    $node = $event->getNode();
    $emoji = match ($node->getName()) {
        'smile' => '😊',
        'heart' => '❤️',
        'rocket' => '🚀',
        default => ':' . $node->getName() . ':',
    };
    $event->setHtml($emoji);
});

// Add target="_blank" to external links
$renderer->addEventListener('render.link', function (RenderEvent $event) {
    $link = $event->getNode();
    $url = $link->getDestination();
    if (str_starts_with($url, 'http')) {
        $link->setAttribute('target', '_blank');
        $link->setAttribute('rel', 'noopener noreferrer');
    }
});

use Djot\Node\Inline\Link;
use Djot\Node\Inline\Text;

$parser = $converter->getParser()->getInlineParser();

// @mentions → profile links
$parser->addInlinePattern('/@([a-zA-Z0-9_]+)/', function ($match, $groups, $p) {
    $link = new Link('/users/' . $groups[1]);
    $link->appendChild(new Text('@' . $groups[1]));
    return $link;
});

// #hashtags → tag pages
$parser->addInlinePattern('/#([a-zA-Z][a-zA-Z0-9_]*)/', function ($match, $groups, $p) {
    $link = new Link('/tags/' . strtolower($groups[1]));
    $link->appendChild(new Text('#' . $groups[1]));
    return $link;
});

echo $converter->convert('Hey @john, check out #PHP!');
// <p>Hey <a href="/users/john">@john</a>, check out <a href="/tags/php">#PHP</a>!</p>

Feature Restriction: Profiles

SafeMode prevents XSS attacks, but what about controlling which markup features users can access? A comment section probably shouldn’t allow headings, tables, or raw HTML – not because they’re dangerous, but because they’re inappropriate for that context.

That’s where Profiles come in. They complement SafeMode by restricting available features based on context:

use Djot\Profile;

// Comment sections: basic formatting only
$converter = new DjotConverter(profile: Profile::comment());

// Blog posts: rich formatting, but no raw HTML
$converter = new DjotConverter(profile: Profile::article());

// Chat messages: text, bold, italic - that's it
$converter = new DjotConverter(profile: Profile::minimal());

$converter = new DjotConverter(
    safeMode: true,
    profile: Profile::comment()
);

$profile = Profile::comment();
echo $profile->getReasonDisallowed('heading');
// "Headings would disrupt page hierarchy in user comments"

echo $profile->getReasonDisallowed('raw_block');
// "Raw HTML could bypass template styling and security measures"

use Djot\LinkPolicy;

// Only allow links to your own domain
$profile = Profile::comment()
    ->setLinkPolicy(LinkPolicy::internalOnly());

// Or whitelist specific domains
$profile = Profile::comment()
    ->setLinkPolicy(
        LinkPolicy::allowlist(['docs.php.net', 'github.com'])
            ->withRelAttributes(['nofollow', 'ugc'])
    );

$converter = new DjotConverter(profile: Profile::minimal());
$html = $converter->convert('# Heading attempt');
// Renders: <p>Heading attempt</p> (text preserved, heading stripped)

$profile = Profile::minimal()->setDefaultAction(Profile::ACTION_STRIP);
// Or for APIs:
$profile = Profile::minimal()->setDefaultAction(Profile::ACTION_ERROR);

Architecture

The package uses a clean separation of concerns:

• BlockParser – Parses block-level elements (headings, lists, tables, code blocks, etc.)
• InlineParser – Processes inline elements within blocks (emphasis, links, code spans)
• HtmlRenderer – Converts the AST to HTML output

This AST-based approach makes the codebase maintainable and opens possibilities for alternative output formats.

There are also other compatibility renderers available, as well as converters to convert existing markup to Djot.

WordPress Plugin: Djot Markup for WP

Want to use Djot in your WordPress site? There’s now a dedicated plugin that brings full Djot support to WordPress.

IDE Support: IntelliJ Plugin

For developers using PhpStorm, IntelliJ IDEA, or other JetBrains IDEs, there’s now an official Djot plugin available.

Performance

How fast is it? We benchmarked djot-php against Djot implementations in other languages:

*Python comparison uses Markdown parsers since no Djot implementation exists for Python.

Key observations: – PHP processes ~2-3 MB/s of Djot content consistently – Performance scales linearly O(n) with document size – Safe mode and Profiles have negligible performance impact – Comparable to Python, ~2x slower than JavaScript reference implementation

For typical blog posts and comments (1-10 KB), parsing takes under 5 ms. A 1 MB document converts in ~530 ms using ~44 MB RAM.

The performance documentation includes detailed benchmarks, memory profiling, and stress test results.

Enhancements & Extensions

The library and the WP plugin already have some useful and powerful extensions, notably:

• Full attribute support
• Boolean Attribute Shorthand
• Fenced Comment Blocks
• Multiple Definition Terms and Definition Descriptions
• Captions for Images, Tables, and Block Quotes
• Markdown compatibility mode (Significant Newlines)

These extend beyond the current spec but are documented as such. Keep this in mind if you need cross-application compatibility.

There is also a highlight.js extension available to also code highlight djot content.

Importing and Migration

You can often with a boolean flag just continue to support the current markup, and with new content add djot based content. For those that want to migrate, there is some built in tooling and converters: – HtmlToDjot – MarkdownToDjot – BbcodeToDjot

Fun fact: They also serve as a nice round-trip validation, to check if the transformation from and to is loss-free. Send a doc into it and reverse it, and the content should still “match” without loss of supported structures.

What’s Next?

The library is actively maintained with plans for:

• Additional renderers (convert Djot back for interoperability)
• More converters
• More markup supported (not contradicting the specs)
• Maybe some framework specific plugins or integrations

Contributions welcome!

Some personal notes

I would have liked URLs and images to have a bit more friendly syntax as well, e.g. [link: url "text"] style for links and [image: src "alt"] style for images. The ![](url) style still feels a bit too much like code syntax to me.

If I were ever to invent a new markup language, I would probably take a similar approach, but try to keep it even simpler by default. The {} braces seem a bit heavy for these common use cases, and for non-technical users.

One of the quirks I had to get used to, was the automated flow (line breaks are ignored) and the need for the visible (hard) line break if really desired. But in the end it usually helps to keep clear paragraphs. And I added compatibility options as opt-in for upgrading or usability ease.

Overall, Djot strikes a great balance between familiarity and consistency. And at least topics like URL/image can be easily added as extension if desired.

The PHP implementation with djot-php library is the most complete implementation of the standard available. It is perfectly suited for web-based usage. Make sure to check out the live sandbox and play around with the complex examples!

Links

• Live Sandbox – Try it in your browser
• GitHub Repository
• Djot Official Site

Give Djot PHP a try in your next project. The familiar syntax with improved consistency and a lot more out of the box might just win you over.