README

Djot markup language integration for Symfony — Twig filters, services, forms, and validation.

Installation

composer require php-collective/symfony-djot

Usage

Twig Filter

{# Safe by default - XSS protection enabled #}
{{ article.body|djot }}

{# For trusted content only - no XSS protection #}
{{ trustedContent|djot_raw }}

{# Plain text output #}
{{ article.body|djot_text }}

Service

use PhpCollective\SymfonyDjot\Service\DjotConverterInterface;

class ArticleController
{
    public function show(DjotConverterInterface $djot): Response
    {
        $html = $djot->toHtml($article->body);
        $text = $djot->toText($article->body);
    }
}

Configuration

# config/packages/symfony_djot.yaml
symfony_djot:
    converters:
        # Default has safe_mode: true (XSS protection enabled)
        default: ~

        # For trusted content (admin, CMS)
        trusted:
            safe_mode: false
    cache:
        enabled: false
        pool: cache.app

Multiple Converter Profiles

Use different configurations for different contexts:

{# Default is safe #}
{{ comment.body|djot }}

{# Use named converter for trusted content #}
{{ article.body|djot('trusted') }}

{# Or use djot_raw for quick trusted rendering #}
{{ article.body|djot_raw }}

public function __construct(
    // Default converter (safe mode enabled)
    private DjotConverterInterface $djot,

    // Trusted converter (safe mode disabled)
    #[Autowire(service: 'symfony_djot.converter.trusted')]
    private DjotConverterInterface $trusted,
) {}

Safe Mode

Safe mode is enabled by default for XSS protection. Disable only for trusted content:

symfony_djot:
    converters:
        trusted:
            safe_mode: false

Extensions

Enable djot-php extensions per converter:

symfony_djot:
    converters:
        default:
            extensions:
                - type: autolink
                - type: smart_quotes
                - type: heading_permalinks
                  symbol: '#'
                  position: after
        with_mentions:
            extensions:
                - type: mentions
                  user_url_template: 'https://github.com/{username}'
                - type: table_of_contents

Available extensions:

• admonition - Admonition blocks (note, tip, warning, danger, etc.)
• autolink - Auto-convert URLs to clickable links
• code_group - Transform code-group divs into tabbed interfaces
• default_attributes - Add default attributes to elements by type
• external_links - Configure external link behavior (target, rel)
• frontmatter - Parse YAML/TOML/JSON frontmatter blocks
• heading_level_shift - Shift heading levels up/down
• heading_permalinks - Add anchor links to headings
• heading_reference - Link to headings with [text](#heading) syntax
• inline_footnotes - Convert spans with class to inline footnotes
• mentions - Convert @username to profile links
• mermaid - Render Mermaid diagram code blocks
• semantic_span - Convert spans to <kbd>, <dfn>, <abbr> elements
• smart_quotes - Convert straight quotes to typographic quotes
• table_of_contents - Generate TOC from headings
• tabs - Tabbed content blocks (CSS or ARIA mode)
• wikilinks - Support [[Page Name]] wiki-style links

See Extensions documentation for detailed configuration options.

Form Type

Use the DjotType for form fields that accept Djot markup:

use PhpCollective\SymfonyDjot\Form\Type\DjotType;

$builder->add('body', DjotType::class);

Validation

Validate that a field contains valid Djot markup:

use PhpCollective\SymfonyDjot\Validator\Constraints\ValidDjot;

class Article
{
    #[ValidDjot]
    private string $body;
}

Documentation

Full documentation: php-collective.github.io/symfony-djot

• Installation
• Configuration
• Twig Usage
• Service Usage
• Forms
• Validation
• Safe Mode
• Extensions
• Caching
• Djot Syntax

Demo Application

See the symfony-djot-demo for a complete example application.

What is Djot?

Djot is a modern light markup language created by John MacFarlane (author of CommonMark/Pandoc). It offers cleaner syntax and more features than Markdown while being easier to parse.

Learn more about Djot syntax at djot.net.