Extensions

The package supports all djot-php extensions. Extensions are configured per converter profile in config/djot.php.

Configuration

// config/djot.php
return [
    'converters' => [
        'default' => [
            'extensions' => [
                ['type' => 'autolink'],
                ['type' => 'smart_quotes'],
            ],
        ],
    ],
];

Shorthand string form is also accepted when no options are needed:

'extensions' => [
    'autolink',
    'smart_quotes',
    'semantic_span',
],

Available Extensions

admonition

Creates styled admonition blocks (callouts) for notes, warnings, tips, etc.

[
    'type' => 'admonition',
    'types' => ['note', 'tip', 'warning', 'danger', 'info', 'success'],
    'default_title' => true,
    'title_tag' => 'p',
    'title_class' => 'admonition-title',
    'container_class' => 'admonition',
    'icons' => true,
    'icon_class' => 'admonition-icon',
]

Usage in Djot:

::: note
This is a note.
:::

::: warning Custom Title
This is a warning with a custom title.
:::

autolink

Automatically converts bare URLs and email addresses to clickable links.

[
    'type' => 'autolink',
    'allowed_schemes' => ['https', 'http', 'mailto'],
]

code_group

Transforms code-group divs into tabbed code block interfaces. Labels are extracted from the language hint using [Label] suffix syntax.

[
    'type' => 'code_group',
    'wrapper_class' => 'code-group',
    'panel_class' => 'code-group-panel',
    'label_class' => 'code-group-label',
    'radio_class' => 'code-group-radio',
    'id_prefix' => 'codegroup',
]

Usage in Djot:

::: code-group

``` php [PHP]
echo "Hello";
```

``` js [JavaScript]
console.log("Hello");
```

:::

default_attributes

Adds default attributes to elements by type.

[
    'type' => 'default_attributes',
    'defaults' => [
        'image' => [
            'loading' => 'lazy',
            'decoding' => 'async',
        ],
        'table' => [
            'class' => 'table table-striped',
        ],
    ],
]

external_links

Configures behavior for external links (adds target="_blank" and security attributes).

[
    'type' => 'external_links',
    'internal_hosts' => ['example.com', 'localhost'],
    'target' => '_blank',
    'rel' => 'noopener noreferrer',
    'nofollow' => false,
]

frontmatter

Parses YAML, TOML, or JSON frontmatter blocks at the start of documents.

[
    'type' => 'frontmatter',
    'default_format' => 'yaml',
    'render_as_comment' => true,
]

heading_level_shift

Shifts all heading levels by a specified amount. Useful when embedding content.

[
    'type' => 'heading_level_shift',
    'shift' => 1, // 1-5
]

heading_permalinks

Adds anchor links to headings for easy linking.

[
    'type' => 'heading_permalinks',
    'symbol' => '#',
    'position' => 'after',
    'class' => 'heading-anchor',
    'aria_label' => 'Permalink',
]

heading_reference

Creates links to headings using [text](#heading-id) syntax.

[
    'type' => 'heading_reference',
    'css_class' => 'heading-ref',
]

inline_footnotes

Converts spans with a specific class to inline footnotes.

[
    'type' => 'inline_footnotes',
    'css_class' => 'fn',
]

mentions

Converts @username references to profile links.

[
    'type' => 'mentions',
    'user_url_template' => 'https://github.com/{username}',
    'user_class' => 'mention',
]

mermaid

Renders code blocks with mermaid language as Mermaid diagrams.

[
    'type' => 'mermaid',
    'tag' => 'pre',
    'css_class' => 'mermaid',
    'wrap_in_figure' => false,
    'figure_class' => 'mermaid-figure',
]

semantic_span

Converts span attributes to semantic HTML5 elements.

['type' => 'semantic_span']

Usage in Djot:

[Ctrl+C]{kbd}                                    → <kbd>Ctrl+C</kbd>
[API]{dfn="Application Programming Interface"}  → <dfn title="...">API</dfn>
[HTML]{abbr="HyperText Markup Language"}         → <abbr title="...">HTML</abbr>

smart_quotes

Converts straight quotes to typographic (curly) quotes.

[
    'type' => 'smart_quotes',
    'locale' => 'en',
]

table_of_contents

Generates a table of contents from headings. Use {toc} placeholder in your document.

[
    'type' => 'table_of_contents',
    'min_level' => 1,
    'max_level' => 6,
    'toc_class' => 'toc',
]

tabs

Creates tabbed content blocks. Supports CSS-only or ARIA modes.

[
    'type' => 'tabs',
    'mode' => 'css',
    'wrapper_class' => 'tabs',
    'tab_class' => 'tabs-panel',
    'label_class' => 'tabs-label',
    'radio_class' => 'tabs-radio',
    'id_prefix' => 'tabset',
]

wikilinks

Supports [[Page Name]] wiki-style links.

[
    'type' => 'wikilinks',
    'url_template' => '/wiki/{page}',
    'link_class' => 'wiki-link',
]

Using Multiple Converters

Define different converter profiles for different use cases:

'converters' => [
    'default' => [
        'extensions' => [
            'autolink',
            'smart_quotes',
        ],
    ],

    'documentation' => [
        'extensions' => [
            'heading_permalinks',
            'table_of_contents',
        ],
    ],

    'user_content' => [
        'safe_mode' => true,
        'extensions' => [
            [
                'type' => 'mentions',
                'user_url_template' => '/users/{username}',
            ],
        ],
    ],
],

Use in Blade:

@djot($article->body)
{!! Djot::toHtml($docs->content, 'documentation') !!}
{!! Djot::toHtml($comment->text, 'user_content') !!}

Or inject the manager and pick the converter:

public function __construct(
    private DjotManager $djot,
) {}

public function renderDocs(string $content): string
{
    return $this->djot->converter('documentation')->toHtml($content);
}