robotstxt-documentation-markdown/README.md

# 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)

```bash
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

```bash
# 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:
```bash
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

```bash
# 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](https://poedit.net/) 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](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](LICENSE) file for details.

## Credits

**Developed by:** ROBOTSTXT

**Dependencies:**
- [league/commonmark](https://commonmark.thephpleague.com/) - Markdown parser
- [WordPress Coding Standards](https://github.com/WordPress/WordPress-Coding-Standards)

## Support

- **Documentation:** See `/docs/` directory
- **Issues:** [Gitea Issues](https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/issues)
- **Discussions:** [Gitea Discussions](https://git.robotstxt.es/ROBOTSTXT/robotstxt-documentation-markdown/discussions)
- **Website:** [ROBOTSTXT.es](https://www.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