336 lines
9.3 KiB
Markdown
336 lines
9.3 KiB
Markdown
# 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
|