WP Djot Documentation

March 25, 2026 · View on GitHub

Usage

Block Editor (Gutenberg)

Add a Djot block from the block inserter (search for "Djot"). The block provides:

A code editor for writing Djot markup
Live preview toggle in the sidebar
Server-side rendering for accurate output

Simply write your Djot content and toggle preview to see the rendered HTML.

Shortcode

[djot]
# Hello World

This is _emphasized_ and this is *strong*.

- List item 1
- List item 2

```php
echo "Hello, World!";
```
[/djot]

Curly Brace Syntax

If content filtering is enabled in settings:

{djot}
Your Djot content here...
{/djot}

Template Tags

// Convert and return HTML
$html = wpdjot_to_html('# Hello *World*!');

// Convert and echo HTML
wpdjot_the('# _Hello_ *World*!');

// Check if content has Djot
if (wpdjot_has($content)) {
    // ...
}

Shortcode Attributes

[djot safe="true"]
Untrusted content - will use safe mode
[/djot]

[djot class="my-custom-class"]
Content with custom CSS class
[/djot]

Configuration

Go to Settings → Djot Markup to configure:

Content Settings: Enable/disable for posts, pages, comments
Comment Processing: Process full comment content as Djot (not just {djot} blocks)
Security Settings: Safe mode for XSS protection, content profiles
Rendering Settings: Line break handling and Markdown compatibility mode
Code Highlighting: Enable/disable and choose theme
Table of Contents: Automatic TOC generation from headings
Advanced: Custom shortcode tag, filter priority

The plugin can automatically generate a table of contents from headings in your posts and pages.

Setting	Options	Default	Description
Enable TOC	on/off	off	Enable automatic TOC generation
Position	top / bottom	top	Where to insert the TOC in the content
Min heading level	H1–H6	H2	Start collecting headings from this level (H2 skips the page title)
Max heading level	H1–H6	H4	Stop collecting headings at this level
List type	ul / ol	ul	Bulleted or numbered list

The TOC is rendered as a collapsible <details class="wpdjot-toc"> element (collapsed by default). Click the "Table of Contents" header to expand it. It includes light and dark mode styling out of the box.

The TOC is only generated for posts and pages (article context), not for comments.

Heading Permalinks

Enable heading permalinks to add clickable # symbols to headings. The symbols appear on hover and clicking copies the heading's URL to the clipboard, making it easy to share links to specific sections.

Setting	Options	Default	Description
Heading Permalinks	on/off	off	Add `#` permalink symbols to headings

Permalinks are only added to posts and pages (article context), not comments. The setting is located in the Table of Contents section of the admin settings.

Experimental

These features are not yet fully stable and may change in future versions.

Visual Editor

The visual editor provides a WYSIWYG editing experience for Djot blocks, powered by Tiptap.

Setting	Description
Disabled	Visual editor tab is hidden. Only Write and Preview modes available. (Default)
Enabled (Write default)	Visual editor available. Write mode is selected by default when opening documents.
Enabled (Visual default)	Visual editor available and selected by default when opening documents.

The visual editor supports most Djot formatting including headings, bold, italic, links, images, lists, tables, code blocks, and more. Some advanced features (like raw HTML) are only available in Write mode.

Note: The visual editor converts Djot to an internal format and back. Some edge cases or custom formatting may not round-trip perfectly. For critical content, verify in Write mode before saving.

Rendering Settings

Markdown Compatibility Mode

Enable this if you're migrating from Markdown and haven't converted your content yet. When enabled:

Single line breaks become visible <br> tags
Blocks (lists, blockquotes, code) can interrupt paragraphs without blank lines

Warning: This deviates from the Djot specification.

Line Break Modes

Control how single line breaks (soft breaks) are rendered:

Mode	Description
Default (invisible)	Standard Djot behavior - line breaks are not visible in output
Space	Render as a space character
Visible line break	Render as `<br>` tag - useful for poetry, addresses, or lyrics

Separate settings are available for posts/pages and comments.

Optional: HTMLPurifier for Enhanced Security

For additional XSS protection on comments, you can optionally install HTMLPurifier:

composer require ezyang/htmlpurifier

When installed, HTMLPurifier will automatically be used for sanitizing comment output.