Skip to content

Commit 96d27fa

Browse files
dereuromarkdereuromark
committed
Simplify README with example, move usage to docs
1 parent c21e674 commit 96d27fa

File tree

2 files changed

+118
-99
lines changed

2 files changed

+118
-99
lines changed

‎README.md‎

Lines changed: 30 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -19,131 +19,62 @@ Djot is a light markup syntax created by John MacFarlane (creator of CommonMark
1919
- **Full Djot Support**: Headings, emphasis, links, images, code blocks, tables, footnotes, and more
2020
- **Block Editor Support**: Native Gutenberg block for writing Djot with live preview
2121
- **Shortcode Support**: Use `[djot]...[/djot]` in your content
22-
- **Content Filtering**: Automatically process `{djot}...{/djot}` blocks in posts and pages
2322
- **Content Profiles**: Configurable feature restrictions (full, article, comment, minimal)
24-
- **Safe Mode**: XSS protection for untrusted content (enabled by default for comments)
23+
- **Safe Mode**: XSS protection for untrusted content
2524
- **Syntax Highlighting**: Built-in highlight.js integration with multiple themes
26-
- **Admin Settings**: Easy configuration through WordPress admin
27-
- **Template Tags**: `wp_djot_to_html()` and `wp_djot_the()` for theme developers
28-
- **Dark Mode Support**: CSS automatically adapts to dark mode preferences
29-
- **WP-CLI Migration**: Migrate existing HTML/Markdown content to Djot with rollback support
25+
- **WP-CLI Migration**: Migrate existing HTML/Markdown content to Djot
3026

31-
## Requirements
32-
33-
- PHP 8.2 or higher
34-
- WordPress 6.0 or higher
35-
- Composer (for installation)
36-
37-
## Installation
27+
## Example
3828

39-
### From GitHub
40-
41-
1. Clone or download this repository to `wp-content/plugins/wp-djot`
42-
2. Run `composer install` in the plugin directory
43-
3. Activate the plugin in WordPress admin
44-
45-
```bash
46-
cd wp-content/plugins/wp-djot
47-
composer install
4829
```
49-
50-
### From WordPress.org
51-
52-
Search for "Djot Markup" in the WordPress plugin directory, or visit:
53-
[wordpress.org/plugins/djot-markup-for-wp](https://wordpress.org/plugins/djot-markup-for-wp/)
54-
55-
## Usage
56-
57-
### Block Editor (Gutenberg)
58-
59-
Add a **Djot** block from the block inserter (search for "Djot"). The block provides:
60-
61-
- A code editor for writing Djot markup
62-
- Live preview toggle in the sidebar
63-
- Server-side rendering for accurate output
64-
65-
Simply write your Djot content and toggle preview to see the rendered HTML.
66-
67-
### Shortcode
68-
69-
````
70-
[djot]
71-
# Hello World
30+
# Welcome to My Blog
7231
7332
This is _emphasized_ and this is *strong*.
7433
75-
- List item 1
76-
- List item 2
34+
Here's a [link to Djot](https://djot.net/) and some `inline code`.
7735
78-
```php
79-
echo "Hello, World!";
80-
```
81-
[/djot]
82-
````
83-
84-
### Curly Brace Syntax
36+
- First item
37+
- Second item
38+
- Third item
8539
86-
If content filtering is enabled in settings:
87-
88-
```
89-
{djot}
90-
Your Djot content here...
91-
{/djot}
92-
```
40+
> A blockquote with some wisdom.
9341
94-
### Template Tags
42+
And a code block:
9543
96-
```php
97-
// Convert and return HTML
98-
$html = wp_djot_to_html('# Hello *World*!');
99-
100-
// Convert and echo HTML
101-
wp_djot_the('# _Hello_ *World*!');
102-
103-
// Check if content has Djot
104-
if (wp_djot_has($content)) {
105-
// ...
106-
}
44+
``` php
45+
<?php
46+
echo "Hello, World!";
10747
```
108-
109-
### Shortcode Attributes
110-
11148
```
112-
[djot safe="true"]
113-
Untrusted content - will use safe mode
114-
[/djot]
11549
116-
[djot class="my-custom-class"]
117-
Content with custom CSS class
118-
[/djot]
119-
```
50+
## Requirements
12051
121-
## Configuration
52+
- PHP 8.2 or higher
53+
- WordPress 6.0 or higher
12254
123-
Go to **Settings → Djot Markup** to configure:
55+
## Installation
12456
125-
- **Content Settings**: Enable/disable for posts, pages, comments
126-
- **Comment Processing**: Process full comment content as Djot (not just `{djot}` blocks)
127-
- **Security Settings**: Safe mode for XSS protection
128-
- **Code Highlighting**: Enable/disable and choose theme
129-
- **Advanced**: Custom shortcode tag, filter priority
57+
### From WordPress.org
13058
131-
### Optional: HTMLPurifier for Enhanced Security
59+
Search for "Djot Markup" in the WordPress plugin directory, or visit:
60+
[wordpress.org/plugins/djot-markup-for-wp](https://wordpress.org/plugins/djot-markup-for-wp/)
13261
133-
For additional XSS protection on comments, you can optionally install HTMLPurifier:
62+
### From GitHub
13463
13564
```bash
136-
composer require ezyang/htmlpurifier
65+
cd wp-content/plugins
66+
git clone https://github.com/php-collective/wp-djot.git
67+
cd wp-djot
68+
composer install --no-dev
13769
```
13870

139-
When installed, HTMLPurifier will automatically be used for sanitizing comment output.
140-
14171
## Documentation
14272

143-
- [Content Profiles](docs/profiles.md) - Configure feature restrictions for posts and comments
144-
- [WP-CLI Commands](docs/wp-cli.md) - Migrate existing content to Djot
73+
- [Usage & Configuration](docs/README.md) - Getting started guide
74+
- [Content Profiles](docs/profiles.md) - Configure feature restrictions
75+
- [WP-CLI Commands](docs/wp-cli.md) - Migrate existing content
14576
- [Hooks and Filters](docs/hooks.md) - Customize plugin behavior
146-
- [Djot Syntax](docs/syntax.md) - Quick reference for Djot markup
77+
- [Djot Syntax](docs/syntax.md) - Quick reference
14778

14879
For complete Djot syntax documentation, visit [djot.net](https://djot.net/).
14980

@@ -155,4 +86,4 @@ For complete Djot syntax documentation, visit [djot.net](https://djot.net/).
15586

15687
## Changelog
15788

158-
See [CHANGELOG.md](CHANGELOG.md) for full history.
89+
See [CHANGELOG.md](CHANGELOG.md) for version history.

‎docs/README.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,93 @@
11
# WP Djot Documentation
22

3+
## Usage
4+
5+
### Block Editor (Gutenberg)
6+
7+
Add a **Djot** block from the block inserter (search for "Djot"). The block provides:
8+
9+
- A code editor for writing Djot markup
10+
- Live preview toggle in the sidebar
11+
- Server-side rendering for accurate output
12+
13+
Simply write your Djot content and toggle preview to see the rendered HTML.
14+
15+
### Shortcode
16+
17+
````
18+
[djot]
19+
# Hello World
20+
21+
This is _emphasized_ and this is *strong*.
22+
23+
- List item 1
24+
- List item 2
25+
26+
```php
27+
echo "Hello, World!";
28+
```
29+
[/djot]
30+
````
31+
32+
### Curly Brace Syntax
33+
34+
If content filtering is enabled in settings:
35+
36+
```
37+
{djot}
38+
Your Djot content here...
39+
{/djot}
40+
```
41+
42+
### Template Tags
43+
44+
```php
45+
// Convert and return HTML
46+
$html = wp_djot_to_html('# Hello *World*!');
47+
48+
// Convert and echo HTML
49+
wp_djot_the('# _Hello_ *World*!');
50+
51+
// Check if content has Djot
52+
if (wp_djot_has($content)) {
53+
// ...
54+
}
55+
```
56+
57+
### Shortcode Attributes
58+
59+
```
60+
[djot safe="true"]
61+
Untrusted content - will use safe mode
62+
[/djot]
63+
64+
[djot class="my-custom-class"]
65+
Content with custom CSS class
66+
[/djot]
67+
```
68+
69+
## Configuration
70+
71+
Go to **Settings → Djot Markup** to configure:
72+
73+
- **Content Settings**: Enable/disable for posts, pages, comments
74+
- **Comment Processing**: Process full comment content as Djot (not just `{djot}` blocks)
75+
- **Security Settings**: Safe mode for XSS protection, content profiles
76+
- **Code Highlighting**: Enable/disable and choose theme
77+
- **Advanced**: Custom shortcode tag, filter priority
78+
79+
### Optional: HTMLPurifier for Enhanced Security
80+
81+
For additional XSS protection on comments, you can optionally install HTMLPurifier:
82+
83+
```bash
84+
composer require ezyang/htmlpurifier
85+
```
86+
87+
When installed, HTMLPurifier will automatically be used for sanitizing comment output.
88+
89+
## More Documentation
90+
391
- [Content Profiles](profiles.md) - Configure feature restrictions for posts and comments
492
- [WP-CLI Commands](wp-cli.md) - Migrate existing content to Djot
593
- [Hooks and Filters](hooks.md) - Customize plugin behavior

0 commit comments

Comments
 (0)