LLM Optimization Plugin 🚀🤖

Markdown Mirrors (.md) + llms.txt Builder + Human/Machine Toggle for WordPress

Built by Sanjay Kumar Monu (Sketchweb) 🛠️✨

This plugin helps your WordPress content become easier for AI systems (LLMs), answer engines, and RAG pipelines to read, retrieve, and cite by publishing clean Markdown mirrors, generating a curated /llms.txt, and optionally adding a sleek Human/Machine toggle on the frontend.

---

✅ What you get (at a glance)

• 🧾 Markdown Mirrors for GEO
  Serve https://yoursite.com/your-post.md as a clean Markdown version of your content.

• 🗺️ GEO Sitemaps + Feeds
  Dedicated sitemap + NDJSON feeds to support retrieval workflows.

• 🧠 Curated /llms.txt Builder (Yoast-powered)
  Generates a high-signal index of important URLs (with smart .md preference).

• 🧷 Human/Machine Floating Toggle
  A minimal floating pill that links users (or testers) to the .md version instantly.

• 🤝 Robots.txt Enhancements
  Add sitemap + llms manifest hints, and optionally manage .md rules for different crawlers.

---

🧩 Why this plugin exists

Modern discovery is shifting from “search and click” to “ask and answer.”
If your content is wrapped in heavy HTML, theme markup, widgets, and scripts, an LLM may waste its attention on code instead of meaning.

This plugin creates clean, structured, Markdown-first access to your content — while keeping your regular WordPress pages unchanged. ✅

---

📚 Table of Contents

• ✨ Features
• ⚡ Quick Start
• 🔧 Installation
• 🧭 Admin Pages
• 🧾 Markdown Mirrors (How it works)
• 🗂️ GEO Endpoints (Sitemaps + Feeds)
• 🧠 llms.txt Builder
• 🧷 Human/Machine Toggle
• 🤖 Robots.txt behavior
• ❓ FAQ
• 🛠️ Troubleshooting
• 🔐 Privacy & Security
• 🧑‍💻 Contributing
• 📄 License

---

✨ Features

1) 🧾 Markdown Mirrors (.md)

• Serve .md versions of posts/pages automatically:
  • /index.md (homepage)
  • /{anything}.md (post/page mirrors)
• Converts your post HTML into Markdown (headings, lists, links, code blocks, tables, etc.)
• Adds optional front-matter (great for structured extraction):
  • title
  • meta description
  • canonical URL
  • published/updated time
  • author
  • categories/tags
  • llm summary + priority

2) 🗺️ GEO Sitemaps + Feeds

Helpful if you want a clean “machine-facing surface”:

• /geo-sitemap.xml (index)
• /geo-sitemap-{posttype}.xml
• /geo-md-sitemap.xml
• /geo-llm-feed.ndjson (summary-friendly feed)
• /geo-embeddings.ndjson (text-forward feed)
• /geo-canonical-map.json
• /geo-chunks.json?post=ID-or-slug
• /geo-status.json

3) 🧠 /llms.txt Builder (Curated + SEO-aware)

• Builds a curated list of your most important pages/posts.
• Pulls SEO titles/descriptions from Yoast SEO when available ✅
• Can prefer .md URLs:
  • off (never use .md)
  • auto (use .md only if it exists)
  • always (always use .md)

Delivery modes:

• virtual (served via rewrite rule)
• physical (writes a real llms.txt in your site root)

Also includes:

• Weekly regeneration cron ⏱️
• One-click “Regenerate Now” button 🟦

4) 🧷 Human/Machine Floating Toggle

• Adds a minimal floating pill on the frontend
• Links to the .md version of the current page
• Adds:
  • <link rel="alternate" type="text/markdown" href="...">
• Config options:
  • enable/disable
  • show only on singular pages
  • open machine version in new tab
  • adjust mobile/desktop bottom offsets

---

⚡ Quick Start (Recommended Setup)

1. ✅ Install + activate the plugin
2. 🔁 Go to Settings → Permalinks and click Save (flush rewrite rules)
3. 🧾 Enable Markdown mirrors in LLM Optimization → Markdown & GEO
4. 🧠 Generate /llms.txt in LLM Optimization → LLMs.txt Builder
5. 🧷 (Optional) Enable the floating toggle in LLM Optimization → Human/Machine Toggle

---

🔧 Installation

Option A: Install via ZIP

1. Download the plugin ZIP from GitHub
2. WordPress Admin → Plugins → Add New → Upload Plugin
3. Activate ✅

Option B: Manual install

1. Copy the plugin folder into:
   wp-content/plugins/llm-optimization-plugin/
2. Activate ✅

After activation, do this once:

• 🔁 Settings → Permalinks → Save Changes

---

🧭 Admin Pages (Where to find everything)

In WordPress Admin, look for:

• 🧠 LLM Optimization → Overview
• 🧾 LLM Optimization → Markdown & GEO
• 📄 LLM Optimization → LLMs.txt Builder
• 🧷 LLM Optimization → Human/Machine Toggle
• 🌐 LLM Optimization → Endpoints (quick links + health view)

---

🧾 Markdown Mirrors (How it works)

When someone requests a .md URL:

• The plugin resolves the matching WordPress post/page
• Pulls SEO title/description (Yoast if installed)
• Converts HTML content to Markdown
• Outputs a clean Markdown doc (optionally with front-matter)

✅ Test it

Try:

• https://yoursite.com/index.md
• https://yoursite.com/your-post-slug.md

---

🗂️ GEO Endpoints Reference

Endpoint	Format	Purpose
/geo-llms-manifest.txt	text/plain	Lists all .md URLs (great for AI discovery)
/index.md	text/markdown	Homepage Markdown mirror
/{path}.md	text/markdown	Post/page Markdown mirrors
/geo-sitemap.xml	XML	Sitemap index for GEO surfaces
/geo-sitemap-{posttype}.xml	XML	Per-posttype sitemap (posts/pages etc.)
/geo-md-sitemap.xml	XML	Sitemap that specifically lists .md URLs
/geo-llm-feed.ndjson	NDJSON	LLM-friendly feed (title/summary/tldr/questions)
/geo-embeddings.ndjson	NDJSON	Text-forward feed for embeddings pipelines
/geo-canonical-map.json	JSON	URL → canonical + md_url mapping
/geo-chunks.json?post=...	JSON	Heading-based chunks for a specific post
/geo-status.json	JSON	Health stats + endpoint links

---

🧠 llms.txt Builder

✅ What it generates

• A curated Markdown-style index of key pages/posts.
• Uses Yoast SEO title/description when available.
• Can prefer .md links automatically.

Delivery Modes

• 🪄 Virtual: serves /llms.txt dynamically
• 🧱 Physical: writes llms.txt to web root (requires permissions)

.md preference modes

• off: always use normal URLs
• auto: use .md only if it exists (checked via HEAD + cached)
• always: always use .md

---

🧷 Human/Machine Toggle

The toggle is designed to be:

• minimal 🧊
• fast ⚡
• unobtrusive 👌

It only appears when:

• enabled in settings
• not in admin / feeds / previews
• not already on a .md page

You can also control visibility via a filter:

add_filter('lop_toggle_should_show', function($show, $settings){
  // Example: hide on homepage
  if (is_front_page()) return false;
  return $show;
}, 10, 2);