Diagnostics & Troubleshooting Guide

Resolve header negotiation conflicts, inspect live Markdown output using the built-in Extraction Diagnostics console, and troubleshoot CDN caching configurations.

1. Using Live Extraction Diagnostics (Pro)

The Pro add-on includes an in-dashboard testing console located under Settings → AI Markdown → Diagnostics. You can test any published post or page directly from your browser:

Enter Target URL or Post ID

Input any public post URL to simulate how the plugin parses the DOM and resolves selectors.

Select Simulation Client

Choose between standard browser, ChatGPT-User, ClaudeBot, PerplexityBot, or Googlebot to test policy matching.

Inspect Markdown Output & Token Metrics

View the raw markdown stream, token count estimates, and header negotiation status in real-time.

2. Common Issues & Solutions

Issue: AI Crawlers Receiving Cached HTML from CDN

Cause: Your edge CDN (e.g. Cloudflare, Fastly) might be caching standard HTML without respecting the Vary: Accept header.

Solution: Ensure your CDN caching rules include Vary header forwarding, or enable the Pro Cloudflare Targeted Purge integration to automatically synchronize edge caches on post updates.

Issue: Navigation Menus or Sidebars Appearing in Markdown

Cause: Non-standard theme markup wrapping body text in generic container tags.

Solution: Navigate to Settings → AI Markdown → Selectors and add your theme's content container selector (e.g. .entry-content, article.post) or exclude unwanted widgets using negative selectors.

Issue: License Status Showing "License server temporarily unreachable"

Cause: Temporary outgoing network timeout between your WordPress server and Lemon Squeezy's API.

Solution: The plugin automatically activates a 14-day Grace Period to ensure Pro features remain completely uninterrupted while connectivity recovers.

3. Terminal Diagnostic Commands

Quick commands to test and isolate issues on your live server:

Terminal / Bash Header Inspection

# Inspect full response headers without downloading the body
curl -I -H "Accept: text/markdown" https://your-site.com/my-article/

# Verify that Googlebot receives HTML and not Markdown
curl -I -A "Googlebot" -H "Accept: text/markdown" https://your-site.com/my-article/

Healthy Diagnostics

Content-Type: text/markdown; charset=UTF-8
Vary: Accept, User-Agent
X-AI-Markdown-Cache: HIT

What to Avoid

Testing through non-standard proxy layers that strip HTTP headers.
Disabling the Vary header in web server configuration files (nginx/apache).