A Visual Studio Code extension that provides live preview and validation for WordPress plugin readme.txt files with pixel-perfect WordPress.org rendering and comprehensive compliance checking.
✅ Live Preview - Real-time rendering matching WordPress.org appearance
✅ Comprehensive Validation - WordPress.org compliance with precise error positioning
✅ Syntax Highlighting - Enhanced editing experience for readme.txt files
✅ Smart Error Detection - Inline highlighting with exact column positioning
✅ Context Menus - Right-click support in explorer and editor tabs
✅ Scroll Synchronization - Keep editor and preview in sync when scrolling
✅ Theme Support - Automatic dark/light theme matching with VS Code
✅ Forced Background Modes - Override preview to always light or dark
✅ Quality Scoring - Get 0-100 quality score with improvement suggestions
✅ False Positive Prevention - Accurate detection without hallucinated errors
✅ Tabbed wordpress.org Layout - Authentic multi-tab presentation (Description, Installation, FAQ, Screenshots, Changelog)
✅ Accessible Screenshot Gallery - Keyboard & screen reader friendly with thumbnails
Multiple Ways to Open:
- Right-click on
readme.txtfile → "Open Preview" - Right-click on editor tab → "Open Preview"
- Editor toolbar → Click preview button (📖)
- Command Palette → "WordPress Readme: Open Preview"
Automatic validation:
- Runs as you type with real-time feedback
- Precise line/column error positioning
- View all issues in Problems panel
- Status bar shows validation status
Manual validation:
- Right-click → "Validate Readme"
- Command Palette → "WordPress Readme: Validate Readme"
- Click status bar validation indicator
- Right-click → "Open Preview to the Side"
- Editor toolbar → "Open Preview to the Side" button
- Command Palette → "WordPress Readme: Open Preview to the Side"
- Scroll Synchronization - Automatically keeps editor and preview scrolled to the same position
Required Header Fields:
- ✅ Plugin Name (
=== Plugin Name ===) - ✅ Contributors (WordPress.org usernames)
- ✅ Tags (1-5 recommended tags)
- ✅ Requires at least (WordPress version)
- ✅ Tested up to (WordPress version)
- ✅ Stable tag (plugin version)
- ✅ License (GPL-compatible)
- ✅ Short description (≤150 characters)
Advanced Content Validation:
- 🎯 Precise Error Positioning - Exact line/column highlighting
- 🚫 False Positive Prevention - Smart detection avoids hallucinated errors
- 📏 Length Validation - Character limits for descriptions and notices
- 🔗 URL Validation - Donate links and license URIs
- 📝 Section Structure - Proper heading hierarchy and formatting
- 🏷️ Version Format - Semantic versioning compliance
- 📊 File Size - WordPress.org size recommendations
Quality Scoring (0-100):
- Real-time scoring as you edit
- Detailed suggestions for improvement
- WordPress.org best practice compliance
- Bonus points for recommended sections
Smart Detection:
- ❌ No false "pro" warnings - Won't flag "provided", "process", "project"
- ❌ No false email warnings - Only flags actual email addresses
- ✅ Context-aware validation - Understands WordPress readme structure
Full compatibility with WordPress.org rendering:
- Bold and italic text formatting
Inline codewith proper HTML escaping (<?php code(); ?>)- Fenced code blocks with syntax highlighting
- Links - Both inline
[text](url)and reference-style[text][ref] - Link titles -
[WordPress](https://wordpress.org "Title")with hover text - Reference definitions -
[ref]: https://example.com(properly hidden) - Ordered and unordered lists with nesting
-
Blockquotes for emphasis
- Video embeds (YouTube, Vimeo, VideoPress)
- FAQ sections with
= Question =format - Version headers in changelog
= 1.0 =
Accurate Rendering:
- Matches WordPress.org plugin directory exactly
- Proper HTML escaping for security
- Responsive design for different screen sizes
- WordPress.org color scheme and typography
- Auto Theme Matching - Seamlessly adapts to VS Code's dark/light theme
All settings live under the wordpress-readme.* namespace.
| Setting | Type | Default | Description |
|---|---|---|---|
wordpress-readme.preview.autoOpen |
boolean | false | Auto-open preview when a readme.txt is opened |
wordpress-readme.preview.theme |
enum(classic | wordpress-org) | classic |
wordpress-readme.preview.backgroundMode |
enum(auto | light | dark) |
wordpress-readme.preview.syncScrolling |
boolean | false | Synchronize scroll position between editor & preview |
wordpress-readme.validation.enabled |
boolean | true | Enable live validation |
wordpress-readme.validation.showWarnings |
boolean | true | Include warnings (not just errors) |
wordpress-readme.contextMenu.showInExplorer |
boolean | true | Show commands in Explorer context menu |
wordpress-readme.contextMenu.showInEditorTab |
boolean | true | Show commands in editor tab context menu |
wordpress-readme.contextMenu.showInEditor |
boolean | true | Show commands in editor content (text area) context menu |
wordpress-readme.contextMenu.showPreview |
boolean | true | Enable "Open Preview" entries |
wordpress-readme.contextMenu.showPreviewToSide |
boolean | true | Enable "Open Preview to the Side" entries |
wordpress-readme.contextMenu.showValidation |
boolean | true | Enable validation command entries |
Example customization snippet:
Use backgroundMode to view your readme in a fixed light or dark palette regardless of the editor theme. Great for checking color/contrast of inline badges or screenshots.
Tags are rendered as simple uppercase bracketed items (e.g. [SEO] [CACHE]) for clarity and compactness—mirroring a neutral, style-light presentation for quick scanning.
| Command | Access Method | Description |
|---|---|---|
WordPress Readme: Open Preview |
Command Palette, Context Menu | Open preview in current editor group |
WordPress Readme: Open Preview to the Side |
Toolbar, Context Menu | Open side-by-side preview |
WordPress Readme: Validate Readme |
Context Menu, Command Palette | Run validation and show detailed results |
Right-click anywhere for quick access:
- File Explorer - Right-click
readme.txtfile - Editor Tab - Right-click on the tab title
- Editor Content - Right-click inside the editor
All context menus provide instant access to preview and validation commands.
Seamless Navigation:
- Automatic Syncing - Editor and preview panels stay synchronized while scrolling
- Bidirectional - Scroll in either the editor or preview to sync both
- Configurable - Enable/disable via
wordpress-readme.preview.syncScrollingsetting - Smooth Performance - Optimized for responsive scrolling without lag
- Side-by-Side Mode - Works perfectly when preview is opened to the side
How it works:
- Open preview to the side for best experience
- Scroll in the editor → preview follows automatically
- Scroll in the preview → editor follows automatically
- Percentage-based positioning ensures accurate alignment
- Temporary sync-lock prevents infinite scroll loops
Automatic Theme Detection:
- VS Code Integration - Automatically matches your current VS Code theme
- Dark Theme - High contrast colors optimized for dark backgrounds
- Light Theme - Clean, readable colors for light backgrounds
- High Contrast - Enhanced visibility for accessibility themes
- Real-time Switching - Instantly adapts when you change VS Code themes
Theme Features:
- Smart Color Variables - Uses VS Code's native color tokens
- Proper Contrast - Ensures readability in all theme variants
- Consistent Branding - Maintains WordPress.org visual identity
- Border & Shadow Adaptation - Adjusts visual elements for each theme
- Code Block Styling - Theme-aware syntax highlighting backgrounds
You can switch to an alternative WordPress.org–style tabbed layout that more closely mirrors the official plugin directory presentation.
Setting:
"wordpress-readme.preview.theme": "wordpress-org" // default is "classic"Features of the wordpress-org theme:
- Tabbed interface (Description, Installation, FAQ, Screenshots, Changelog, Reviews placeholder)
- Banner + Icon rendering (auto-detected)
- Responsive, accessible screenshot gallery (thumbnails + keyboard navigation + focus outlines)
- Keyboard navigation: Arrow keys / Home / End across tabs and thumbnails
- Deep linking using URL hash (e.g.
#faqselects the FAQ tab) - Graceful placeholders when a tab has no content
If a tab has no corresponding content it displays a subtle placeholder. Reviews are not locally generated (placeholder only).
When using the wordpress-org theme the extension automatically searches for standard plugin assets next to your readme.txt:
Search order (first existing directory wins precedence if duplicates):
.wordpress-org/assets/
Supported file patterns (case-insensitive):
- Banners:
banner-1544x500.(png|jpg)(large),banner-772x250.(png|jpg)(small) - Icons:
icon-256x256.*,icon-128x128.*,icon-64x64.*,icon-32x32.*(.png,.jpg,.jpeg,.svg) - Screenshots:
screenshot-1.(png|jpg|jpeg|gif),screenshot-2.*, etc.
The best available icon size is chosen in order: 256 → 128 → 64 → 32. Screenshots are displayed in ascending numerical order.
If no assets are found the layout gracefully omits the banner/icon/screenshot areas.
This mirrors the conventions used by WordPress.org so you can visually QA your assets before publishing. Gallery supports:
- Click thumbnail to swap main image
- Arrow key navigation through thumbnails
- Esc returns focus to the gallery container (when implemented in webview focus scope)
- Maintains aspect ratio and centers images on varied panel widths
Tip: Keep your banner image optimized. WordPress.org expects specific dimensions and reasonable file sizes for performance.
The extension automatically activates for:
- Files named
readme.txt - Files with
.txtextension (when they contain WordPress readme content)
- Visual Studio Code 1.74.0 or higher
- No additional dependencies required
- TypeScript - Type-safe development with full IntelliSense
- Custom Parser - Purpose-built WordPress readme.txt parser
- Precise Validation - Line/column accurate error positioning
- WordPress.org Compliance - Matches official validation standards
- Performance Optimized - Real-time validation without lag
- ✅ Section Header Regex - Fixed false matches with plugin names
- ✅ Inline Code Rendering - Proper HTML escaping for
<?php ?> - ✅ False Positive Prevention - Smart promotional language detection
- ✅ Diagnostic Updates - No duplicate errors, proper refresh
- ✅ Column Positioning - Exact error highlighting
✅ Good:
=== My Plugin ===
Contributors: myusername
Tags: tag1, tag2
Requires at least: 5.0
Tested up to: 6.3
❌ Issues Detected:
- Missing required fields (Contributors, Tags, etc.)
- Invalid version formats ("latest" instead of "6.3")
- Overly promotional language ("Best Ultimate Plugin")
- Actual email addresses in content
- Short descriptions over 150 characters
- 📖 WordPress Plugin Readme Standard
- 🔍 Official Readme Validator
- 🏪 WordPress Plugin Directory
- 📋 Plugin Development Guidelines
- 🎨 WordPress.org Design Patterns
Common Issues:
- No syntax highlighting? → File must be named
readme.txt - Validation not running? → Check settings:
wordpress-readme.validation.enabled - Context menu missing? → Reload VS Code window after installation
- Preview not updating? → Ensure file is saved (auto-save recommended)
🐛 Bug Reports: Open issues with specific readme.txt examples
💡 Feature Requests: Suggest improvements for WordPress.org compliance
🔧 Pull Requests: Contributions welcome for parser and validation improvements
GPL-2.0-or-later © 2025 Per Soderlind
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.
Enjoying the extension? Star the repository or open an issue with feedback. Happy publishing!
{ "wordpress-readme.preview.theme": "wordpress-org", "wordpress-readme.preview.backgroundMode": "dark", "wordpress-readme.preview.syncScrolling": true, "wordpress-readme.validation.showWarnings": false }