Add BbcodeToDjot

Author: dereuromark

README.md

@@ -98,31 +98,22 @@ https://sandbox.dereuromark.de/sandbox/djot
 - [Examples](docs/README.md) - Comprehensive usage examples
 - [Syntax Reference](docs/syntax.md) - Complete Djot syntax guide
 - [API Reference](docs/api.md) - Classes and methods
+- [Converters](docs/converters.md) - Markdown/BBCode to Djot conversion
 - [Cookbook](docs/cookbook.md) - Common customizations and recipes
 - [Architecture](docs/architecture.md) - Internal design
 
 ## Security
 
-**Warning:** When processing untrusted user input, sanitize the output to prevent XSS attacks. We recommend using [HTMLPurifier](http://htmlpurifier.org/):
+When processing untrusted user input, enable safe mode for XSS protection:
 
 ```php
-$converter = new DjotConverter();
+$converter = new DjotConverter(safeMode: true);
 $html = $converter->convert($untrustedInput);
-
-$config = HTMLPurifier_Config::createDefault();
-$config->set('Cache.DefinitionImpl', null);
-$config->set('HTML.DefinitionID', 'djot-purifier');
-$config->set('HTML.DefinitionRev', 1);
-$config->set('HTML.Allowed', 'p,br,strong,em,u,s,del,ins,mark,sub[id],sup[id],a[href|title|class|id],img[src|alt|title],ul,ol,li,dl,dt,dd,blockquote,pre,code[class],h1[id],h2[id],h3[id],h4[id],h5[id],h6[id],table[class|id],thead,tbody,tr,th[align],td[align],hr,div[class|id],span[class|id],section[id]');
-$config->set('Attr.EnableID', true);
-$config->set('HTML.TargetBlank', true);
-$config->set('URI.AllowedSchemes', ['http' => true, 'https' => true, 'mailto' => true]);
-
-$purifier = new HTMLPurifier($config);
-$safeHtml = $purifier->purify($html);
 ```
 
-See [Security Considerations](docs/README.md#security-considerations) for details.
+Safe mode automatically blocks dangerous URL schemes (`javascript:`, etc.), strips event handler attributes (`onclick`, etc.), and escapes raw HTML.
+
+See [Security Considerations](docs/README.md#security-considerations) for details and advanced configuration.
 
 ## See Also
 

docs/README.md

@@ -8,6 +8,7 @@ This directory contains detailed documentation for djot-php.
 - [API Reference](api.md) - Classes and methods
 - [Cookbook](cookbook.md) - Common customizations and recipes
 - [Architecture](architecture.md) - Internal design
+- [Converters](converters.md) - Markdown/BBCode to Djot conversion
 
 ## Examples
 
@@ -373,9 +374,37 @@ See the [Cookbook](cookbook.md) for more examples including wiki links, hashtags
 - Event handler attributes (e.g., `onclick`)
 - Raw HTML blocks and inline HTML
 
-### Recommended: Use HTMLPurifier
+### Recommended: Use Safe Mode
 
-For user-generated content, sanitize the HTML output using [HTMLPurifier](http://htmlpurifier.org/):
+Enable the built-in safe mode for XSS protection:
+
+```php
+use Djot\DjotConverter;
+
+// Enable with sensible defaults
+$converter = new DjotConverter(safeMode: true);
+$html = $converter->convert($userInput);
+```
+
+Safe mode automatically:
+- Blocks dangerous URL schemes (`javascript:`, `vbscript:`, `data:`, `file:`)
+- Strips event handler attributes (`onclick`, `onload`, etc.)
+- Escapes raw HTML (or strips it in strict mode)
+
+For stricter protection, use `SafeMode::strict()`:
+
+```php
+use Djot\DjotConverter;
+use Djot\SafeMode;
+
+$converter = new DjotConverter(safeMode: SafeMode::strict());
+```
+
+See the [API Reference](api.md#safe-mode) for full SafeMode configuration options.
+
+### Alternative: Use HTMLPurifier
+
+For maximum control over allowed HTML, you can also use [HTMLPurifier](http://htmlpurifier.org/):
 
 ```bash
 composer require ezyang/htmlpurifier

docs/api.md

@@ -17,13 +17,15 @@ $html = $converter->convert($djotString);
 public function __construct(
     bool $xhtml = false,
     bool $warnings = false,
-    bool $strict = false
+    bool $strict = false,
+    bool|SafeMode|null $safeMode = null
 )
 ```
 
 - `$xhtml`: When `true`, produces XHTML-compatible output (self-closing tags like `<br />`).
 - `$warnings`: When `true`, collects warnings during parsing (see [Error Handling](#error-handling)).
 - `$strict`: When `true`, throws `ParseException` on parse errors (see [Error Handling](#error-handling)).
+- `$safeMode`: When `true` or a `SafeMode` instance, enables XSS protection (see [Safe Mode](#safe-mode)).
 
 ### Methods
 
@@ -133,6 +135,124 @@ public function clearWarnings(): self
 
 Clears any collected warnings.
 
+#### setSafeMode
+
+```php
+public function setSafeMode(bool|SafeMode|null $safeMode): self
+```
+
+Enable, disable, or configure safe mode after construction. Pass `true` for defaults, a `SafeMode` instance for custom configuration, or `null`/`false` to disable.
+
+## Safe Mode
+
+Safe mode provides built-in XSS protection for user-generated content.
+
+### Basic Usage
+
+```php
+use Djot\DjotConverter;
+
+// Enable with sensible defaults
+$converter = new DjotConverter(safeMode: true);
+$html = $converter->convert($userInput);
+```
+
+### What Safe Mode Does
+
+1. **URL Sanitization**: Blocks dangerous URL schemes in links and images
+   - Blocked by default: `javascript:`, `vbscript:`, `data:`, `file:`
+   - Safe URLs like `https:`, `mailto:`, and relative paths are allowed
+
+2. **Attribute Filtering**: Strips event handler attributes
+   - Blocks attributes starting with `on` (e.g., `onclick`, `onload`, `onerror`)
+   - Blocks specific dangerous attributes (`srcdoc`, `formaction`)
+   - Allows safe attributes like `class`, `id`, `data-*`
+
+3. **Raw HTML Handling**: Controls how raw HTML is processed
+   - `escape` (default): HTML-encodes raw HTML so it displays as text
+   - `strip`: Removes raw HTML entirely
+   - `allow`: Passes raw HTML through (not recommended)
+
+### SafeMode Class
+
+```php
+use Djot\SafeMode;
+
+// Factory methods
+$safeMode = SafeMode::defaults();  // Standard protection
+$safeMode = SafeMode::strict();    // Strips raw HTML completely
+```
+
+#### Configuration Methods
+
+```php
+// URL scheme control
+$safeMode->setDangerousSchemes(['javascript', 'vbscript', 'data']);
+$safeMode->addDangerousScheme('ftp');
+$safeMode->getDangerousSchemes();
+
+// Whitelist approach (only these schemes allowed)
+$safeMode->setAllowedSchemes(['https', 'mailto']);
+$safeMode->getAllowedSchemes();
+
+// Attribute filtering
+$safeMode->setBlockedAttributePrefixes(['on']);  // Blocks onclick, onload, etc.
+$safeMode->setBlockedAttributes(['srcdoc', 'formaction']);
+$safeMode->getBlockedAttributePrefixes();
+$safeMode->getBlockedAttributes();
+
+// Raw HTML handling
+$safeMode->setRawHtmlMode(SafeMode::RAW_HTML_ESCAPE);  // Default
+$safeMode->setRawHtmlMode(SafeMode::RAW_HTML_STRIP);   // Remove completely
+$safeMode->setRawHtmlMode(SafeMode::RAW_HTML_ALLOW);   // Pass through
+$safeMode->getRawHtmlMode();
+```
+
+#### Validation Methods
+
+```php
+$safeMode->isUrlSafe('https://example.com');     // true
+$safeMode->isUrlSafe('javascript:alert(1)');    // false
+
+$safeMode->isAttributeSafe('class');            // true
+$safeMode->isAttributeSafe('onclick');          // false
+
+$safeMode->sanitizeUrl('javascript:alert(1)');  // ''
+$safeMode->filterAttributes([
+    'class' => 'highlight',
+    'onclick' => 'hack()',
+]);  // ['class' => 'highlight']
+```
+
+### Custom Configuration Example
+
+```php
+use Djot\DjotConverter;
+use Djot\SafeMode;
+
+// Only allow HTTPS links, strip raw HTML
+$safeMode = SafeMode::defaults()
+    ->setAllowedSchemes(['https'])
+    ->setRawHtmlMode(SafeMode::RAW_HTML_STRIP);
+
+$converter = new DjotConverter(safeMode: $safeMode);
+```
+
+### Enabling After Construction
+
+```php
+$converter = new DjotConverter();
+
+// Enable later
+$converter->setSafeMode(true);
+
+// Or with custom config
+$converter->setSafeMode(SafeMode::strict());
+
+// Disable
+$converter->setSafeMode(false);
+```
+
 ## Error Handling
 
 The parser can optionally report warnings and errors with line/column information.
@@ -429,25 +549,95 @@ $renderer->setTableCellSeparator(' | ');
 
 ### MarkdownRenderer
 
-Renders an AST Document to CommonMark-compatible Markdown.
+Renders an AST Document to CommonMark-compatible Markdown. Useful for:
+- Converting Djot content to Markdown for systems that only support Markdown
+- Migrating content between formats
+- Generating Markdown documentation from Djot source
 
 ```php
+use Djot\DjotConverter;
 use Djot\Renderer\MarkdownRenderer;
 
+$converter = new DjotConverter();
+$document = $converter->parse($djotText);
+
 $renderer = new MarkdownRenderer();
 $markdown = $renderer->render($document);
 ```
 
+**Conversion Table:**
+
+| Djot | Markdown Output |
+|------|-----------------|
+| `*strong*` | `**strong**` |
+| `_emphasis_` | `*emphasis*` |
+| `{-deleted-}` | `~~deleted~~` (GFM) |
+| `{+inserted+}` | `<ins>inserted</ins>` |
+| `{=highlighted=}` | `<mark>highlighted</mark>` |
+| `^superscript^` | `<sup>superscript</sup>` |
+| `~subscript~` | `<sub>subscript</sub>` |
+| `` `code` `` | `` `code` `` |
+| `[text](url)` | `[text](url)` |
+| `![alt](src)` | `![alt](src)` |
+| `# Heading` | `# Heading` |
+| `> quote` | `> quote` |
+| `- list` | `- list` |
+| `1. ordered` | `1. ordered` |
+| `- [ ] task` | `- [ ] task` |
+| `:symbol:` | `:symbol:` |
+| `[^note]` | `[^note]` |
+| `$math$` | `$math$` |
+| `$$display$$` | `$$display$$` |
+| Tables | GFM tables with alignment |
+| Divs | Content only (no wrapper) |
+| Spans | Content only (no wrapper) |
+| Definition lists | Bold term + `: description` |
+| Line blocks | Hard breaks (`  \n`) |
+| Raw HTML | Passed through |
+| Comments | Stripped |
+
 **Behavior:**
-- Converts Djot to CommonMark Markdown
-- Uses GFM extensions where available (strikethrough with `~~`)
-- Falls back to HTML for features without Markdown equivalents:
-  - Superscript: `<sup>text</sup>`
-  - Subscript: `<sub>text</sub>`
-  - Highlight: `<mark>text</mark>`
-  - Insert: `<ins>text</ins>`
-- Preserves table alignment
-- Preserves footnotes
+- Produces CommonMark-compatible output
+- Uses GFM extensions where available (strikethrough, tables, task lists, footnotes)
+- Falls back to inline HTML for features without Markdown equivalents
+- Escapes special Markdown characters in text content
+- Handles nested backticks in code spans and fenced blocks
+- Preserves table column alignment
+- Normalizes multiple blank lines
+
+**Example:**
+
+```php
+$djot = <<<'DJOT'
+# Hello *World*
+
+This has {=highlighted=} and {-deleted-} text.
+
+| Name  | Score |
+|-------|------:|
+| Alice |    95 |
+DJOT;
+
+$document = $converter->parse($djot);
+$markdown = (new MarkdownRenderer())->render($document);
+```
+
+Output:
+```markdown
+# Hello **World**
+
+This has <mark>highlighted</mark> and ~~deleted~~ text.
+
+| Name | Score |
+| --- | ---: |
+| Alice | 95 |
+```
+
+**Limitations:**
+- Djot divs (`::: class`) lose their class/attributes (content is preserved)
+- Djot spans (`[text]{.class}`) lose their attributes (content is preserved)
+- Definition lists are approximated (not native Markdown)
+- Some whitespace/formatting may differ from original
 
 ## AST Node Types