=== Documentation Markdown (by ROBOTSTXT) ===
Contributors: robotstxt
Tags: github, documentation, markdown, sync, automation
Requires at least: 6.7
Tested up to: 7.0
Requires PHP: 8.2
Stable tag: 1.1.0
License: GPLv3 or later
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Synchronize Markdown documentation from GitHub repositories to WordPress pages and posts automatically.

== Description ==

**Documentation Markdown** is a powerful WordPress plugin that enables seamless synchronization of Markdown documentation files from GitHub repositories into your WordPress site. Perfect for maintaining technical documentation, API references, knowledge bases, and more - all with the power of version control.

= Key Features =

* 🔄 **Automatic Synchronization** - Schedule automatic syncs via WordPress Cron (hourly, twice daily, daily)
* 📝 **Markdown to HTML** - Convert GitHub Flavored Markdown to clean HTML using CommonMark
* 🎯 **Flexible Mapping** - Map individual MD files to specific WordPress posts or pages
* 🔐 **Secure** - Encrypted GitHub token storage, full input validation & output escaping
* 🌍 **Translatable** - Full internationalization support (i18n/l10n ready)
* 📚 **Multi-Repository** - Sync from multiple GitHub repos simultaneously
* ⚡ **Manual Sync** - On-demand synchronization from admin interface
* 🐛 **Debug Tools** - Built-in debugging tools (visible when WP_DEBUG is enabled)

= Use Cases =

* **API Documentation** - Keep your API docs in sync between GitHub and WordPress
* **Technical Documentation** - Maintain version-controlled technical docs
* **Knowledge Base** - Build a knowledge base powered by GitHub
* **Blog Posts** - Write blog posts in Markdown with Git workflow
* **Product Documentation** - Sync product documentation from your repository
* **Multi-language Documentation** - Manage translations in GitHub, publish to WordPress

= How It Works =

1. Configure your GitHub Personal Access Token in plugin settings
2. Create mappings between GitHub Markdown files and WordPress content
3. Choose synchronization frequency (manual, hourly, twice daily, daily)
4. The plugin automatically fetches and converts Markdown to HTML
5. Your WordPress content stays in sync with your GitHub repository

= Requirements =

* PHP 8.2 or higher
* WordPress 6.9 or higher
* GitHub Personal Access Token (free, for accessing repositories)
* Composer (for production build with dependencies)

= Security =

* GitHub tokens encrypted at rest (AES-256-CBC)
* All user input sanitized
* All output escaped
* Nonce verification on all forms
* Capability checks for all admin actions
* Prepared statements for database queries
* Rate limiting for GitHub API

= Developer Friendly =

* Clean, well-documented code
* Follows WordPress Coding Standards (WPCS)
* Modern PHP 8.2+ features
* Extensive PHPDoc documentation
* Procedural approach (KISS principles)
* Extensible with WordPress hooks and filters

== Installation ==

= Automatic Installation =

1. Log in to your WordPress admin panel
2. Navigate to Plugins → Add New
3. Search for "Documentation Markdown ROBOTSTXT"
4. Click "Install Now" and then "Activate"

= Manual Installation =

1. Download the plugin ZIP file
2. Upload to `/wp-content/plugins/` directory
3. Extract the files
4. Ensure Composer dependencies are installed (`composer install --no-dev`)
5. Activate the plugin through the 'Plugins' menu in WordPress

= After Installation =

1. Navigate to 'Documentation → Settings' in the WordPress admin menu
2. Generate a GitHub Personal Access Token:
   - Go to GitHub → Settings → Developer settings → Personal access tokens
   - Click "Generate new token"
   - For public repositories: No specific scopes needed
   - For private repositories: Select `repo` scope
3. Paste your token in the plugin settings and save
4. Create your first mapping under 'Documentation → Mappings'

== Frequently Asked Questions ==

= Do I need a GitHub account? =

Yes, you need a GitHub account to generate a Personal Access Token. The token is required to access repositories (public or private).

= Can I sync from private repositories? =

Yes! When generating your GitHub Personal Access Token, make sure to select the `repo` scope for full access to private repositories.

= How often does synchronization happen? =

You can configure synchronization frequency per mapping:
* Manual only (on-demand via "Sync Now" button)
* Hourly
* Twice daily
* Daily

You can also manually trigger sync at any time.

= Will the plugin delete my WordPress content if I uninstall it? =

By default, NO. When you uninstall the plugin, it preserves all synced WordPress pages/posts. However, there's an option in Settings to delete plugin data on uninstall (mappings, settings, etc.) - but this never deletes the actual WordPress content, only the plugin configuration.

= Can I sync multiple files from the same repository? =

Yes! You can create multiple mappings, each pointing to different files in the same repository or different repositories.

= What Markdown syntax is supported? =

The plugin uses CommonMark (league/commonmark), which supports GitHub Flavored Markdown including:
* Headings, paragraphs, lists
* Code blocks with syntax highlighting
* Tables
* Links and images
* Blockquotes
* And more!

= Does it support images from GitHub? =

Currently, Markdown image links are converted to HTML, but images are not downloaded. Images must be publicly accessible via their GitHub URLs or you need to host them separately.

= Can I customize the HTML output? =

The plugin converts Markdown to standard HTML. You can style the output using your theme's CSS by targeting the content area where documentation is displayed.

= Is there a limit on file size? =

While there's no hard limit imposed by the plugin, GitHub API has size limitations. Very large files (>10MB) may cause issues. We recommend keeping documentation files under 1MB for best performance.

= What happens if GitHub is unavailable? =

If GitHub API is unreachable during a scheduled sync, the plugin will fail gracefully and retry on the next scheduled interval. Your existing content remains unchanged.

= Can I edit synced content in WordPress? =

You can edit synced content in WordPress, but be aware that the next synchronization will overwrite your changes with content from GitHub. We recommend making all edits in your GitHub repository.

= How do I debug synchronization issues? =

Enable WP_DEBUG in your wp-config.php:
```
define('WP_DEBUG', true);
```

Then go to Documentation → Settings, and you'll see a "Debug Tools" section at the bottom with:
* Test GitHub repository connection
* Test GitHub token validity
* View scheduled cron jobs
* Manually run cron jobs
* Clear plugin caches

== Screenshots ==

1. Plugin Settings - Configure GitHub repository and token
2. Mappings List - View all your GitHub-to-WordPress mappings
3. Add/Edit Mapping - Create new mapping between GitHub file and WordPress content
4. Sync Status - Monitor synchronization status and history
5. Debug Tools - Built-in debugging interface (shown when WP_DEBUG is enabled)

== Compatibility ==

* WordPress: 6.7 - 6.9
* PHP: 8.2 - 8.5

== Changelog ==

For the complete changelog, see [changelog.txt](https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/raw/branch/main/changelog.txt).

= 1.1.0 - 2026-03-28 =

**Security**

* Patched CVE-2026-33347 and CVE-2026-30838 (league/commonmark updated to 2.8.2)

**Changed**

* Access level changed from administrator (manage_options) to editor (edit_pages) — editors can now manage documentation mappings without requiring full admin access

**Fixed**

* PHPStan level 9 compliance: zero errors across all plugin files (down from 104)
* target_order (menu_order) field was in the UI but never saved or applied — now fully implemented
* Type-safety improvements for all WordPress API returns (get_option, get_post_meta, json_decode, size_format)
* Token decryption false return handled correctly
* Uninstall data cleanup narrows mixed option return before array access

**Compatibility**

* Verified compatible with WordPress 6.8 and 7.0
* Verified compatible with PHP 8.4.x

= 1.0.0 - 2026-01-26 =

**Initial Release**

* ✨ Core synchronization functionality
* 🔄 Automatic scheduled sync (hourly, twice daily, daily)
* ⚡ Manual on-demand sync
* 📝 Markdown to HTML conversion using CommonMark
* 🎯 Flexible file-to-content mapping system
* 🔐 Encrypted GitHub token storage
* 🌍 Full internationalization support
* 📚 Multi-repository support
* 🎨 Clean admin interface with status badges
* 🔧 Custom Post Type for mapping management
* 📦 Support for pages, posts, and custom post types
* 👤 Configurable post author and parent page
* 🔢 Page order (menu_order) support
* 🐛 Debug tools for troubleshooting
* 🔄 Cron job management and repair tools
* 🧹 Clean uninstall with optional data deletion
* ✅ WordPress Coding Standards compliant
* 🛡️ Security best practices (nonces, escaping, sanitization)

**Admin Features:**
* Settings page for GitHub configuration
* Mappings management interface
* Add/Edit mapping with validation
* Sync status monitoring
* Debug tools (when WP_DEBUG enabled)
  - Test GitHub connection
  - Test token validity
  - View scheduled crons
  - Run crons manually
  - Fix cron schedules
  - Clear plugin caches

**Developer Features:**
* Procedural PHP following KISS principles
* PHP 8.2+ modern features
* Complete PHPDoc documentation
* WordPress hooks and filters
* Extensible architecture
* PHPCS and PHPStan validated

== Upgrade Notice ==

= 1.0.0 =
Initial release of Documentation Markdown. Sync your GitHub Markdown files to WordPress automatically!

== Additional Information ==

= Support =

* **Documentation:** Comprehensive docs included in `/docs/` directory
* **Repository:** [Report issues](https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/issues)
* **Website:** [ROBOTSTXT.es](https://www.robotstxt.es/)
* **Security:** robotstxt@robotstxt.es

= Contributing =

We welcome contributions! Please visit our [Gitea repository](https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown) to:
* Report bugs
* Suggest features
* Submit pull requests

= Privacy =

This plugin does not collect or store any user data. The only external connection made is to the GitHub API to fetch repository content. Your GitHub Personal Access Token is encrypted and stored locally in your WordPress database.

= Credits =

Developed by ROBOTSTXT with ❤️

**Dependencies:**
* [league/commonmark](https://commonmark.thephpleague.com/) - Markdown parser and converter

= License =

This plugin is licensed under the GNU General Public License v3.0 or later.

== Compliance ==

This plugin adheres to the following security measures and review protocols for each version:

* [WordPress Plugin Handbook](https://developer.wordpress.org/plugins/)
* [WordPress Plugin Security](https://developer.wordpress.org/plugins/wordpress-org/plugin-security/)
* [WordPress APIs Security](https://developer.wordpress.org/apis/security/)
* [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)
* [Plugin Check (PCP)](https://wordpress.org/plugins/plugin-check/)