Documentation Markdown (by ROBOTSTXT) git.robotstxt.es

=== Documentation Markdown (by ROBOTSTXT) === Contributors: robotstxt, javiercasares Tags: github, documentation, markdown, sync, automation Requires at least: 4.2 Tested up to: 7.1 Requires PHP: 8.0 Stable tag: 1.2.2 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.0 or higher
• WordPress 4.2 or higher
• GitHub Personal Access Token (free, for accessing repositories)
• Composer (for production build with dependencies)

= Updates =

Automatic updates for this plugin are delivered through the Manager (by ROBOTSTXT) plugin. Install and activate Manager to receive update notifications.

= 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.0+ 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: 4.2 - 7.1
• PHP: 8.0 - 8.5

== Changelog ==

For the complete changelog, see changelog.txt.

= 1.2.2 - 2026-08-24 =

Changed

• Manager (by ROBOTSTXT) detection now uses the ecosystem presence constant ROBOTSTXT_MANAGER_NOTICED (Manager 1.6.2+), falling back to a plugin-list scan for older Manager versions — same function name and behavior for callers
• New unit tests for both detection paths (constant defined / plugin-list fallback)

Compatibility

• WordPress: 4.2 - 7.1 (floor re-verified with WP-Compat; smoke-tested on 7.2-alpha)
• PHP: 8.0 - 8.5 (floor re-verified with PHPCompatibility 5.6-8.5 full-range scan)

Translations

• Spanish (es_ES) and Catalan (ca): verified complete and in sync (156 strings, no changes needed)

= 1.2.1 - 2026-08-17 =

Changed

• Automatic updates are now delivered through the Manager (by ROBOTSTXT) plugin: the built-in self-updater (class-robotstxt-updater.php and update.json) has been removed
• When the Manager plugin is not active, a dismissible notice on the Plugins page and a permanent notice on the plugin Settings page recommend installing it
• Minimum WordPress lowered to 4.2 — the real lowest version the code runs on, verified with WP-Compat (wp_delete_file(), available since 4.2, is the oldest API used)
• Plugin URI and Update URI now point to https://www.robotstxt.software/plugins/robotstxt-documentation-markdown/

Security

• league/commonmark updated to 2.10.0 (via composer update)

Compatibility

• WordPress: 4.2 - 7.1
• PHP: 8.0 - 8.5

Translations

• Spanish (es_ES) and Catalan (ca): 10 missing strings from 1.2.0 added, plus the new Manager notice

= 1.2.0 - 2026-08-07 =

Added

• Title from H1: the synced post title is now taken from the first # H1 in the Markdown (inline formatting stripped), with the H1 removed from the body to avoid a duplicate heading. Falls back to the filename-derived title when no H1 is present
• Internal link translation: repo-relative Markdown links (e.g. ./api.md, ../README.md) are rewritten to the permalink of the matching mapped WordPress content. External, mailto:, and anchor links are left untouched; links with no matching mapping keep their original URL
• Repository image sideloading: images referenced in the Markdown are downloaded from the repository, added to the Media Library, and their references replaced with the attachment URL. Already-imported images are reused on subsequent syncs (tracked per post); removed images are kept in the Media Library (non-destructive)

Security

• Patched CVE-2026-71478 (and advisory GHSA-2q4p-g7hv-5rgv) in league/commonmark — an unsafe-link filter bypass that could defeat allow_unsafe_links: false. Updated league/commonmark 2.8.2 → 2.9.0
• GitHub token encryption now derives its AES-256 key with HKDF-SHA256 from wp_salt('auth') instead of using the salt directly; existing tokens are migrated transparently to the new v2: format on first decrypt (covers the cron path too)
• Discover Files "Refresh from GitHub" action is now nonce-protected — previously a crafted link could force an unrequested GitHub API call (CSRF)
• GitHub API request paths are now rawurlencode()d (defensive hardening)
• Sideloaded images are validated by extension (jpg, jpeg, png, gif, webp) and size (< 10 MB) before storage; SVG is intentionally excluded

Fixed

• "Using cached data / fetching fresh data" indicator on Discover Files now reflects reality — it always showed "cached" because the cache was tested after being populated
• target_post_type is now validated against registered public post types on save, falling back to page (prevents saving an unregistered or internal type)
• Debug action dispatch refactored into a single switch, each case retaining its check_admin_referer() check, to reduce the chance of a missing nonce check

Changed

• Inline onclick confirm on Delete replaced with a data-confirm attribute + delegated handler (CSP-friendlier, less fragile)
• Add Mapping "existing content" dropdown now queries only public post types (excludes attachments and the internal mapping CPT) with no_found_rows for better performance on large sites

== Upgrade Notice ==

= 1.2.2 = Manager (by ROBOTSTXT) detection updated: now uses the ROBOTSTXT_MANAGER_NOTICED presence constant (Manager 1.6.2+) with a fallback for older Manager versions.

= 1.2.1 = Automatic updates now require the Manager (by ROBOTSTXT) plugin. A notice with the download link is shown on the Plugins and Settings pages.

== Additional Information ==

= Support =

• Documentation: robotstxt.software
• Updates: Manager (by ROBOTSTXT)
• Website: ROBOTSTXT.software
• Security: robotstxt@robotstxt.es

= Contributing =

We welcome contributions! Please visit our website to:

• Report bugs
• Suggest features

= 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 - 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
• WordPress Plugin Security
• WordPress APIs Security
• WordPress Coding Standards
• Plugin Check (PCP)