A WordPress plugin for Djot markup language support. Convert Djot syntax to HTML in posts, pages, and comments.
Djot is a light markup syntax created by John MacFarlane (creator of CommonMark and Pandoc). It aims to be a successor to Markdown with cleaner syntax and more consistent parsing rules.
- Full Djot Support: Headings, emphasis, links, images, code blocks, tables, footnotes, and more
- Block Editor Support: Native Gutenberg block for writing Djot with live preview
- Shortcode Support: Use
[djot]...[/djot]in your content - Content Filtering: Automatically process
{djot}...{/djot}blocks in posts and pages - Safe Mode: XSS protection for untrusted content (enabled by default for comments)
- Syntax Highlighting: Built-in highlight.js integration with multiple themes
- Admin Settings: Easy configuration through WordPress admin
- Template Tags:
djot_to_html()andthe_djot()for theme developers - Dark Mode Support: CSS automatically adapts to dark mode preferences
- WP-CLI Migration: Migrate existing HTML/Markdown content to Djot with rollback support
- PHP 8.2 or higher
- WordPress 6.0 or higher
- Composer (for installation)
- Clone or download this repository to
wp-content/plugins/wp-djot - Run
composer installin the plugin directory - Activate the plugin in WordPress admin
cd wp-content/plugins/wp-djot
composer installSearch for "WP Djot" in the WordPress plugin directory.
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.
[djot]
# Hello World
This is _emphasized_ and this is *strong*.
- List item 1
- List item 2
```php
echo "Hello, World!";
```
[/djot]
If content filtering is enabled in settings:
{djot}
Your Djot content here...
{/djot}
// Convert and return HTML
$html = djot_to_html('# Hello *World*!');
// Convert and echo HTML
the_djot('# _Hello_ *World*!');
// Check if content has Djot
if (has_djot($content)) {
// ...
}[djot safe="true"]
Untrusted content - will use safe mode
[/djot]
[djot class="my-custom-class"]
Content with custom CSS class
[/djot]
Go to Settings → WP Djot 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
- Code Highlighting: Enable/disable and choose theme
- Advanced: Custom shortcode tag, filter priority
For additional XSS protection on comments, you can optionally install HTMLPurifier:
composer require ezyang/htmlpurifierWhen installed, HTMLPurifier will automatically be used for sanitizing comment output.
| Syntax | Result |
|---|---|
_emphasis_ |
emphasis |
*strong* |
strong |
`code` |
code |
[link](url) |
link |
 |
Image |
# Heading |
Heading (h1-h6) |
> blockquote |
Blockquote |
- item |
Unordered list |
1. item |
Ordered list |
| Syntax | Result |
|---|---|
x^2^ |
Superscript |
H~2~O |
Subscript |
{=marked=} |
Highlighted text |
{+inserted+} |
Inserted text |
{-deleted-} |
Deleted text |
[text]{.class} |
Span with CSS class |
::: note ... ::: |
Div with CSS class |
"quotes" -- Pro |
Smart typography |
Note: Djot uses different emphasis syntax than Markdown:
_underscores_for emphasis (italic) and*single asterisks*for strong (bold).
For complete syntax documentation, visit djot.net.
// Modify Djot content before conversion
add_filter('wp_djot_pre_convert', function(string $djot): string {
// Modify $djot
return $djot;
});
// Modify HTML after conversion
add_filter('wp_djot_post_convert', function(string $html): string {
// Modify $html
return $html;
});Migrate existing HTML or Markdown content to Djot format using WP-CLI.
Analyze posts to determine migration complexity before converting:
# Analyze all posts and pages
wp djot analyze
# Analyze a specific post
wp djot analyze --post-id=123
# Analyze only posts, limit to 10
wp djot analyze --post-type=post --limit=10
# Output as JSON
wp djot analyze --format=jsonThe analysis shows:
- Complexity: none, low, medium, high
- Content types: HTML, Markdown, Gutenberg blocks, shortcodes
- Auto-migrate: Whether the post can be safely auto-migrated
Warning: Always create a full database backup before migrating content. While the plugin stores original content in post meta for rollback, a complete backup is recommended.
Convert posts from HTML/Markdown to Djot:
# Migrate a single post
wp djot migrate --post-id=123
# Preview migration without saving (dry run)
wp djot migrate --dry-run
# Preview with content diff
wp djot migrate --dry-run --show-diff --post-id=123
# Migrate posts in batches
wp djot migrate --post-type=post --limit=10
# Force migration of high-complexity posts
wp djot migrate --post-id=123 --forceFeatures:
- Automatic backup of original content
- Preserves WordPress shortcodes
- Preserves Gutenberg blocks
- Converts HTML tags to Djot syntax
- Converts Markdown syntax to Djot
Restore posts to their original content:
# Rollback a single post
wp djot rollback --post-id=123
# Rollback all migrated posts
wp djot rollback --allView migration statistics:
wp djot statusShows count of migrated posts, pending posts, and complexity distribution.
Migrate comments similarly to posts:
# Analyze all comments
wp djot analyze-comments
# Analyze comments for a specific post
wp djot analyze-comments --post-id=123
# Migrate comments (dry run first)
wp djot migrate-comments --dry-run
# Migrate a specific comment
wp djot migrate-comments --comment-id=456
# Migrate all comments for a post
wp djot migrate-comments --post-id=123
# Force migration of complex comments
wp djot migrate-comments --force
# Rollback a comment
wp djot rollback-comments --comment-id=456
# Rollback all migrated comments
wp djot rollback-comments --all- Djot by John MacFarlane
- djot-php by PHP Collective
- highlight.js for syntax highlighting
See CHANGELOG.md for full history.