Domscribe WordPress Plugin

Automatically serve your WordPress content as Markdown when requested via the Accept: text/markdown HTTP header.

This WordPress plugin uses Domscribe PHP to convert your WordPress pages and posts to semantic Markdown on-the-fly, making your content accessible to Markdown-based applications, AI assistants, and content aggregators.

🚀 Features

• Automatic Markdown Conversion: Serves Markdown when Accept: text/markdown header is present
• Smart Content Extraction: Automatically detects and extracts main content
• Performance Optimized: Built-in caching system for fast responses
• Highly Configurable: Full control via WordPress admin panel
• SEO-Friendly Metadata: Includes post metadata in YAML frontmatter
• Post Type Filtering: Choose which post types to convert
• URL Management: Option to convert URLs to relative paths or reference-style links
• Developer Friendly: Hooks and filters for customization

📦 Installation

Simple Installation (No Composer Required!)

This plugin includes all dependencies bundled in the lib/ directory. No need for Composer!

1. Download the plugin:

   • Download the zip file from releases
   • Or clone: git clone https://github.com/acseo/domscribe-wordpress.git

2. Install:

   • Upload to wp-content/plugins/domscribe-wordpress
   • Or extract zip file in plugins directory

3. Activate:

   • Go to WordPress Admin → Plugins
   • Find "Domscribe WordPress" and click "Activate"

That's it! The plugin is ready to use.

Advanced: Development with Composer (Optional)

For developers who want to use Composer for development tools:

cd wp-content/plugins/domscribe-wordpress
composer install --dev

This installs PHPStan and CodeSniffer for code quality checks, but is not required for the plugin to work.

⚙️ Configuration

Go to Settings → Domscribe in your WordPress admin panel.

Available Options

Option	Description	Default
Enable Markdown Conversion	Master switch for the plugin	On
Extract Main Content	Automatically detect and extract main content	On
Reference-style Links	Convert inline links to reference format	Off
Strip Site URL	Convert absolute URLs to relative paths	On
Enable Caching	Cache converted Markdown for performance	On
Cache Duration	How long to cache results (seconds)	3600
Allowed Post Types	Which post types to convert	Posts, Pages

📖 Usage

Basic Usage

Once activated, any request with the Accept: text/markdown header will receive Markdown:

curl -H "Accept: text/markdown" https://your-site.com/sample-post/

Response Example

---
title: Sample Post Title
author: John Doe
date: 2026-03-09T10:00:00+00:00
url: https://your-site.com/sample-post/
categories: [Technology, Tutorial]
tags: [WordPress, Markdown]
---

# Sample Post Title

This is the main content of your post, automatically converted to Markdown.

## Features

- Automatic conversion
- Smart content extraction
- SEO-friendly output

[Read more](https://example.com)

Testing with cURL

# Get a specific post as Markdown
curl -H "Accept: text/markdown" https://your-site.com/hello-world/

# Save to file
curl -H "Accept: text/markdown" https://your-site.com/hello-world/ > post.md

# Get homepage
curl -H "Accept: text/markdown" https://your-site.com/

Testing with HTTPie

http https://your-site.com/sample-post/ Accept:text/markdown

Testing in Browser

Use browser developer tools to modify the Accept header:

1. Open DevTools (F12)
2. Go to Network tab
3. Right-click on a request → Edit and Resend
4. Modify Accept header to text/markdown
5. Send the request

🔌 Developer Hooks

Filters

Modify Conversion Options

add_filter('domscribe_wp_conversion_options', function($options) {
    // Customize Domscribe conversion options
    $options['refify_urls'] = true;
    $options['custom_option'] = 'value';

    return $options;
});

Modify Markdown Output

add_filter('domscribe_wp_markdown_output', function($markdown, $html) {
    // Modify the final Markdown output
    $markdown = "<!-- Custom header -->\n\n" . $markdown;

    return $markdown;
}, 10, 2);

Actions

Before Conversion

add_action('domscribe_wp_before_conversion', function($post_id) {
    // Do something before HTML is converted
    error_log("Converting post {$post_id} to Markdown");
});

🎯 Use Cases

1. AI and LLM Integration

Allow AI assistants to easily consume your content in Markdown format:

import requests

response = requests.get(
    'https://your-site.com/article/',
    headers={'Accept': 'text/markdown'}
)

markdown_content = response.text
# Process with your AI/LLM

2. Content Aggregation

Build content aggregators that prefer Markdown:

fetch('https://your-site.com/post/', {
    headers: {
        'Accept': 'text/markdown'
    }
})
.then(response => response.text())
.then(markdown => {
    // Process markdown
});

3. Documentation Export

Export WordPress documentation to Markdown files:

#!/bin/bash
posts=(
    "getting-started"
    "api-reference"
    "troubleshooting"
)

for post in "${posts[@]}"; do
    curl -H "Accept: text/markdown" \
        "https://docs.example.com/$post/" \
        > "docs/$post.md"
done

4. Static Site Generation

Use WordPress as a CMS and export to static Markdown:

<?php
// Export all posts to Markdown files
$posts = get_posts(['numberposts' => -1]);

foreach ($posts as $post) {
    $url = get_permalink($post);
    $markdown = file_get_contents($url, false, stream_context_create([
        'http' => [
            'header' => 'Accept: text/markdown'
        ]
    ]));

    file_put_contents(
        "export/{$post->post_name}.md",
        $markdown
    );
}

🔧 Advanced Configuration

Custom Post Type Support

// In your theme's functions.php
add_filter('domscribe_wp_allowed_post_types', function($post_types) {
    $post_types[] = 'product';
    $post_types[] = 'portfolio';

    return $post_types;
});

Custom Metadata

add_filter('domscribe_wp_post_metadata', function($metadata, $post) {
    $metadata['custom_field'] = get_post_meta($post->ID, 'custom_field', true);
    $metadata['reading_time'] = calculate_reading_time($post);

    return $metadata;
}, 10, 2);

🚀 Performance

The plugin includes several performance optimizations:

• Smart Caching: Results are cached with automatic invalidation
• Conditional Processing: Only processes requests with appropriate headers
• Minimal Overhead: Zero impact on normal WordPress requests
• Efficient Conversion: Uses optimized Domscribe PHP library

Benchmark Results

Normal HTML request:     ~100ms
First Markdown request:  ~150ms (conversion)
Cached Markdown request: ~105ms (minimal overhead)

🔍 Troubleshooting

Markdown Not Returning

1. Check plugin is activated
2. Verify "Enable Markdown Conversion" is checked in settings
3. Ensure post type is in allowed list
4. Confirm Accept: text/markdown header is being sent

Cache Issues

Clear cache in Settings → Domscribe → Cache Management

Missing Dependencies Error

The plugin should work out of the box. If you see any errors:

1. Verify the lib/ directory exists and contains files
2. Check PHP version (must be 8.0+)
3. Check file permissions

📝 Requirements

• PHP 8.0 or higher
• WordPress 5.8 or higher
• Composer (for dependency management)

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Credits

• Built with Domscribe PHP
• Developed by ACSEO

🔗 Links

• Documentation
• Issue Tracker
• Domscribe PHP

📞 Support

For support and questions:

• Open an issue on GitHub
• Visit ACSEO