# Maple Code Blocks WordPress Plugin

A beautiful and secure WordPress plugin that displays code files from GitHub repositories in a terminal/IDE-style interface with syntax highlighting.

## Features

✨ **Beautiful Interface**
- Terminal/IDE-style code viewer
- Dark and light themes
- Syntax highlighting for 30+ languages
- Line numbers
- Tabbed interface for multiple files

🔒 **Security First**
- All code is HTML-escaped (no XSS risk)
- Code is displayed as text only, never executed
- Multiple layers of content sanitization
- Binary files automatically filtered
- File size limits to prevent performance issues

🚀 **Functionality**
- File browser with search
- Copy code to clipboard
- Fullscreen mode
- Repository caching for performance
- Responsive design
- AJAX-powered for smooth experience

## Installation

1. Upload the `maple-code-blocks` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure settings in Settings > Maple Code Blocks

# Maple Code Blocks - WordPress Plugin

A beautiful and secure WordPress plugin by **SSP Media** that displays code files from **GitHub, GitLab, Bitbucket, and Codeberg** repositories in a terminal/IDE-style interface with syntax highlighting. Now with **full Gutenberg block editor support**!

## About

**Maple Code Blocks** is developed and maintained by [SSP Media](https://sspmedia.ca/wordpress/), a Canadian web development agency specializing in WordPress solutions.

## Key Features

✅ **Public Access** - Visitors can view code without logging in (configurable)
✅ **Multi-Platform** - Supports GitHub, GitLab, Bitbucket, and Codeberg
✅ **Beautiful Themes** - Dark, Light, Monokai, Solarized
✅ **Gutenberg Ready** - Full block editor support
✅ **Secure** - Rate limiting, XSS protection, OWASP compliant

### Public Viewing Configuration

By default, all visitors can view public repository code. To restrict viewing to logged-in users only:

```php
// Add to your theme's functions.php
add_filter('mcb_require_login_for_viewing', '__return_true');
```

## Supported Formats

### All Platforms Support These Formats:

#### 1. GitHub (default platform)
```
[maple_code_block repo="facebook/react"]
[maple_code_block repo="github:facebook/react"]
```

#### 2. GitLab
```
[maple_code_block repo="gitlab:gitlab-org/gitlab"]
```

#### 3. Bitbucket
```
[maple_code_block repo="bitbucket:atlassian/python-bitbucket"]
```

#### 4. Codeberg
```
[maple_code_block repo="codeberg:forgejo/forgejo"]
```

### Format Guide:
- **Simple format:** `owner/repo` (defaults to GitHub)
- **Platform prefix:** `platform:owner/repo`
- **Platforms:** `github`, `gitlab`, `bitbucket`, `codeberg`

### Full Examples with Options:

✅ **GitHub** - github.com  
✅ **GitLab** - gitlab.com  
✅ **Bitbucket** - bitbucket.org  
✅ **Codeberg** - codeberg.org

## Features

✨ **Beautiful Interface**
- Terminal/IDE-style code viewer
- Dark and light themes
- Syntax highlighting for 30+ languages
- Line numbers
- Tabbed interface for multiple files
- **NEW: Gutenberg block with live preview**
- **NEW: Block variations and patterns**

🔒 **Security First**
- All code is HTML-escaped (no XSS risk)
- Code is displayed as text only, never executed
- Multiple layers of content sanitization
- Binary files automatically filtered
- File size limits to prevent performance issues

🚀 **Functionality**
- File browser with search
- Copy code to clipboard
- Fullscreen mode
- Repository caching for performance
- Responsive design
- AJAX-powered for smooth experience
- **NEW: Visual block editor**
- **NEW: Pre-built block patterns**

## Installation

1. Upload the `maple-code-blocks` folder to `/wp-content/plugins/`
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure settings in Settings > Maple Code Blocks

## Usage

### Method 1: Gutenberg Block (Recommended)

#### Using the Block Editor

1. In the WordPress block editor, click the "+" button to add a new block
2. Search for "Maple Code Blocks"
3. Select the block from the "Maple Code Blocks" category
4. Configure the repository and settings in the block sidebar
5. Preview your code viewer in real-time

#### Block Variations

The plugin includes pre-configured block variations:
- **React Component**: Display React components
- **Documentation Viewer**: Perfect for README files
- **Full Repository Browser**: Browse entire repositories
- **Code Snippet**: Display specific code files
- **Tutorial Code**: Ideal for educational content

#### Block Patterns

Ready-to-use layouts available in the Pattern Library:
- **Code with Explanation**: Code blocks with explanatory text
- **Side-by-Side Comparison**: Compare two implementations
- **Code Gallery**: Showcase multiple examples
- **Featured Code**: Highlight important implementations
- **Tutorial Steps**: Step-by-step code tutorials

#### Block Settings

Configure directly in the block editor sidebar:
- **Repository**: Enter the GitHub repository (owner/repository)
- **Theme**: Choose from Dark, Light, Monokai, or Solarized
- **Height**: Set custom height (px, %, vh, em, rem)
- **Line Numbers**: Toggle line numbers on/off
- **Initial File**: Select a file to display on load
- **Title**: Add an optional title
- **Alignment**: Support for wide and full width

### Method 2: Classic Shortcode

#### Basic Shortcode

```
[maple_code_block repo="owner/repository"]
```

#### Platform-Specific Examples

**GitHub (default):**
```
[maple_code_block repo="facebook/react"]
```

**GitLab:**
```
[maple_code_block repo="gitlab:gitlab-org/gitlab"]
```

**Bitbucket:**
```
[maple_code_block repo="bitbucket:atlassian/python-bitbucket"]
```

**Codeberg:**
```
[maple_code_block repo="codeberg:forgejo/forgejo"]
```

**Using Full URLs:**
```
[maple_code_block repo="https://gitlab.com/fdroid/fdroidclient"]
[maple_code_block repo="https://bitbucket.org/mailchimp/mandrill-api-php"]
[maple_code_block repo="https://codeberg.org/forgejo/forgejo"]
```

### Advanced Options

```
[github_code_viewer 
    repo="facebook/react" 
    theme="dark" 
    height="500px" 
    show_line_numbers="true"
    initial_file="README.md"
    title="React Source Code"]
```

### Parameters

| Parameter | Description | Default |
|-----------|-------------|---------|
| `repo` | GitHub repository (owner/name) | Required |
| `theme` | Color theme (dark/light/monokai/solarized) | dark |
| `height` | Viewer height | 600px |
| `show_line_numbers` | Show line numbers (true/false) | true |
| `initial_file` | File to load initially | none |
| `title` | Title above viewer | none |

## Security Features

### Multiple Layers of Protection

1. **Server-side Escaping**: All content is HTML-escaped using PHP's `htmlspecialchars()`
2. **JavaScript Context Escaping**: Additional escaping for JavaScript contexts
3. **Content Type Validation**: Binary files are automatically detected and rejected
4. **Size Limits**: Files over 1MB are not displayed
5. **Pattern Matching**: Dangerous patterns are replaced with safe alternatives
6. **Safe Rendering**: Code is inserted as text content, never as HTML

### What This Means

- ✅ JavaScript code is displayed but NEVER executed
- ✅ HTML tags are shown as text, not rendered
- ✅ No possibility of XSS attacks
- ✅ Safe to display any code from any public repository
- ✅ WordPress site and database remain completely secure

## Configuration

### GitHub Personal Access Token (Optional)

For public repositories, no token is required. However, GitHub limits unauthenticated requests to 60 per hour. To increase this limit:

1. Go to Settings > Maple Code Blocks
2. [Generate a GitHub token](https://github.com/settings/tokens) (no special permissions needed)
3. Enter the token and save

### Cache Settings

Files are cached for 1 hour by default to improve performance. You can adjust this in the settings.

## Supported Languages

The plugin includes syntax highlighting for:

- JavaScript, TypeScript, JSX, TSX
- Python, Ruby, PHP
- Java, C, C++, C#
- Go, Rust, Swift, Kotlin
- HTML, CSS, SCSS, SASS, LESS
- JSON, XML, YAML
- SQL, Bash, Markdown
- And many more...

## Performance

- **Caching**: Repository contents are cached to reduce API calls
- **Lazy Loading**: Files are loaded on-demand
- **Optimized Rendering**: Syntax highlighting is applied efficiently
- **Responsive**: Works smoothly on all devices

## Styling

The plugin includes four built-in themes:

1. **Dark** - VS Code inspired dark theme
2. **Light** - Clean light theme
3. **Monokai** - Popular Sublime Text theme
4. **Solarized** - Eye-friendly color scheme

## Browser Compatibility

- Chrome/Edge (latest)
- Firefox (latest)
- Safari (latest)
- Opera (latest)

## Requirements

- WordPress 5.0 or higher
- PHP 7.2 or higher
- JavaScript enabled in browser

## Support

For issues, feature requests, or questions, please contact the plugin author or submit a support ticket.

## Support

For support, documentation, and updates, visit [SSP Media WordPress Plugins](https://sspmedia.ca/wordpress/).

## License

GPL v2 or later

---

**Maple Code Blocks** is proudly developed by [SSP Media](https://sspmedia.ca/wordpress/) 🍁

## Changelog

### Version 1.0.0
- Initial release
- Core functionality
- Security features
- Four themes
- Syntax highlighting for 30+ languages

## Credits

- Syntax highlighting powered by a custom lightweight Prism.js implementation
- Icons from various open-source icon sets
- Inspired by VS Code and other modern code editors
