Documentation Markdown (by ROBOTSTXT)

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

Description

Documentation Markdown is a 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.

Features

• 🔄 Automatic Synchronization - Schedule automatic syncs via WordPress Cron
• 📝 Markdown to HTML - Convert GitHub Flavored Markdown to clean HTML
• 🎯 Flexible Mapping - Map individual MD files to specific WordPress posts/pages
• 🔍 Smart Change Detection - Only sync when content actually changes (using SHA comparison)
• 🔐 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

Requirements

• PHP: 8.2 or higher
• WordPress: 6.5 or higher
• GitHub Account: For repository access (public or private)

Installation

Manual Installation

1. Download the plugin or clone this repository
2. Upload to /wp-content/plugins/robotstxt-documentation-markdown/
3. Run composer install --no-dev in the plugin directory
4. Activate the plugin through the 'Plugins' menu in WordPress
5. Navigate to 'GitHub Docs' in the WordPress admin menu
6. Configure your GitHub Personal Access Token
7. Create your first mapping

Via Composer (Development)

cd wp-content/plugins
git clone https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown.git robotstxt-documentation-markdown
cd robotstxt-documentation-markdown
composer install

Configuration

1. GitHub Personal Access Token

Generate a Personal Access Token from GitHub:

• 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
• Copy the token (you won't see it again!)

2. Plugin Configuration

1. In WordPress admin, go to GitHub Docs → Settings
2. Paste your GitHub token
3. Configure sync frequency (hourly, twice daily, daily)
4. Save settings

3. Create a Mapping

1. Go to GitHub Docs → Mappings
2. Click "Add New Mapping"
3. Fill in:
   • Repository Owner: GitHub username or organization
   • Repository Name: Repository name
   • File Path: Path to .md file (e.g., docs/api/auth.md)
   • Branch: Branch to sync from (default: main)
   • Target Post Type: Where to create content (page/post)
   • Author: WordPress user who will be the post author
4. Save mapping
5. Click "Sync Now" to perform first synchronization

Usage Examples

Example 1: API Documentation

Sync your API documentation from GitHub to WordPress pages:

Repository: yourcompany/api-docs
File Path: docs/authentication.md
Branch: main
Target: Page

Every time authentication.md is updated in GitHub, the corresponding WordPress page will automatically update.

Example 2: Blog Posts

Write blog posts in Markdown using Git workflow:

Repository: yourblog/content
File Path: posts/2026-01-intro-to-api.md
Branch: main
Target: Post

Commit your Markdown post to GitHub, and it automatically publishes to your WordPress blog.

Example 3: Knowledge Base

Maintain a knowledge base with version control:

Repository: support/knowledge-base
File Path: articles/how-to-install.md
Branch: production
Target: Page

Development

Setup Development Environment

# Clone repository
git clone https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown.git
cd documentation-markdown

# Install dependencies
composer install

# Run code quality checks
composer phpcs          # Check coding standards
composer phpcbf         # Auto-fix coding standards
composer phpstan        # Static analysis
composer test           # Run tests

Coding Standards

This plugin strictly follows:

• WordPress Coding Standards (WPCS)
• PHP 8.2+ features (readonly properties, constructor promotion, match expressions)
• Complete PHPDoc documentation for all code
• PSR-4 autoloading

All code must pass:

composer lint  # Runs both PHPCS and PHPStan

Documentation

Complete technical documentation available in /docs/:

• 00-REQUIREMENTS-SUMMARY.md - Start here! All critical requirements
• 01-project-overview.md - Plugin overview and use cases
• 02-architecture.md - System architecture and components
• 03-data-structure.md - Database schema and data models
• 04-development-phases.md - Development roadmap
• 05-technical-specifications.md - Technical details and APIs
• 06-synchronization-flow.md - How synchronization works
• 07-security-considerations.md - Security best practices
• 08-implementation-order.md - Step-by-step implementation guide

Running Tests

# Unit tests
composer test

# Specific test
vendor/bin/phpunit tests/test-github-api-client.php

# With coverage
composer test -- --coverage-html coverage/

Security

Reporting Vulnerabilities

Please report security vulnerabilities privately to: robotstxt@robotstxt.es

Do NOT create public issues for security vulnerabilities.

Security Features

• ✅ 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

Translation

The plugin is fully translatable and uses the text domain: robotstxt-documentation-markdown

To translate:

1. Use Poedit or similar tool
2. Open /languages/robotstxt-documentation-markdown.pot
3. Create translations
4. Save as robotstxt-documentation-markdown-{locale}.mo
5. Place in /wp-content/languages/plugins/

Changelog

See CHANGELOG.md for detailed version history.

Version 1.0.0 (2026-01-26)

• ✨ Initial stable release
• 🔄 GitHub repository synchronization
• 📝 Markdown to HTML conversion using CommonMark
• 🎯 Flexible file-to-content mapping
• ⚡ Manual and scheduled synchronization
• 🎨 Complete admin interface
• 🐛 Built-in debug tools (WP_DEBUG mode)
• 🔐 Encrypted token storage
• 🌍 Full internationalization support
• 🛡️ Security best practices implemented

Roadmap

Future enhancements under consideration:

• Bidirectional sync (WordPress → GitHub)
• Image synchronization from GitHub
• Folder-level mapping (sync entire directory)
• GitHub webhooks support (instant sync on push)
• Gutenberg block for embedded docs
• Multi-branch support per mapping
• Conflict resolution UI

Contributing

We welcome contributions! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow WordPress Coding Standards (run composer phpcs)
4. Write PHPDoc for all functions
5. Include unit tests for new functionality
6. Ensure all tests pass (composer test)
7. Commit with conventional commit messages
8. Push to your fork
9. Open a Pull Request

All contributions must:

• Be in English
• Include complete PHPDoc
• Pass PHPCS and PHPStan
• Include appropriate unit tests

License

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

See LICENSE file for details.

Credits

Developed by: ROBOTSTXT

Dependencies:

• league/commonmark - Markdown parser
• WordPress Coding Standards

Support

• Documentation: See /docs/ directory
• Issues: Gitea Issues
• Discussions: Gitea Discussions
• Website: ROBOTSTXT.es
• Security: robotstxt@robotstxt.es

---

Status: Stable Release Version: 1.0.0 Requires PHP: 8.2+ Requires WordPress: 6.5+ (single-site only) License: GPL-3.0-or-later Text Domain: robotstxt-documentation-markdown