=== AEOHelper - Markdown Publisher ===
Contributors: zire
Tags: markdown, llms.txt, aeo, ai visibility, content extraction
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 0.5.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate reviewed Markdown versions of WordPress pages and posts, expose them through page headers, optionally create llms.txt, and monitor Markdown requests.

== Description ==

AEOHelper - Markdown Publisher makes your WordPress content easier for AI systems and other automated tools to discover and process by creating clean, reviewed Markdown versions of the Pages and Posts you choose.

AEOHelper does five main things:

= 1. Generate Markdown versions of selected WordPress Pages and Posts =

Choose the content you want to publish, generate a Markdown preview from the public page, review it, and approve it before anything goes live.

Each approved page receives its own clean Markdown endpoint, such as:

`example.com/your-page/index.md`

Your original HTML page remains unchanged.

= 2. Add Markdown discovery links to your page headers =

For every approved Markdown page, AEOHelper adds an alternate Markdown discovery link to the original page's HTML head.

This gives compatible crawlers and AI systems a direct way to discover the cleaner Markdown representation without replacing or modifying your normal web page.

AEOHelper also sends an HTTP canonical Link header from the Markdown response back to the original HTML page.

= 3. Optionally generate and manage llms.txt =

Create a curated `llms.txt` file containing the Markdown pages you want AI systems to discover.

You can:

* Organise pages into custom sections.
* Control section order and page order.
* Use custom link titles and descriptions.
* Fall back to available WordPress and SEO metadata when custom metadata is not supplied.
* Include only Markdown pages you have reviewed and approved.

The `llms.txt` manager is optional and disabled by default.

= 4. Review and customise what appears in Markdown =

AEOHelper gives you control over the Markdown output before publishing.

You can:

* Exclude content that should not appear in Markdown.
* Add Markdown-only context to explain illustrative or ambiguous content.
* Convert selected visual layouts into structured Markdown tables.
* Review generated Markdown before first publication.
* Choose how approved Markdown should be updated when the source page changes.

Simple data attributes give you extra control without changing what normal website visitors see:

* `data-aeohelper-exclude` - exclude selected content from Markdown.
* `data-aeohelper-context` - add Markdown-only context for AI and automated readers.
* `data-aeohelper-table` - convert selected visual layouts into structured Markdown tables.

Legacy `data-zire-ai-*` attributes remain supported for existing installations.

= 5. Monitor requests to your Markdown content =

Optionally enable local Request Activity to see when your Markdown and `llms.txt` endpoints are requested.

AEOHelper can record:

* Request time.
* Requested endpoint.
* Associated post or page.
* HTTP method.
* Response status.
* General user-agent category.

Request Activity is stored locally in your WordPress database. It does not store IP addresses, cookies or referrers and does not send request records to an external service.

AI-related user-agent names can be categorised for easier monitoring, but user-agent strings can be spoofed, so Request Activity should be treated as a monitoring aid rather than verified crawler analytics.

= Why Markdown? =

Modern WordPress pages can contain navigation, scripts, styling, page-builder markup and other HTML that is useful for browsers but unnecessary when an automated system only needs the underlying content.

A clean Markdown representation removes much of that surrounding markup and presents useful headings, paragraphs, links, lists, tables and other content in a simpler structured format.

This can reduce unnecessary markup and make the important content easier to extract and process.

AEOHelper keeps the original HTML page unchanged and simply provides Markdown as an additional representation.

The plugin does not switch content based on a visitor's user agent and does not send your content to an external AI service.

Markdown availability does not guarantee crawling, indexing, AI recommendations or citations. Support for alternate Markdown discovery and `llms.txt` varies between providers.

== Installation ==

1. Upload and activate AEOHelper - Markdown Publisher on your WordPress site.
2. Open **AEOHelper** from the WordPress administration menu.
3. Choose the Pages or Posts you want to make available as Markdown.
4. Generate a Markdown preview for a selected public Page or Post.
5. Review the generated Markdown, including facts, links, prices, tables, examples and any content you have excluded or added context to.
6. Approve and publish the Markdown when you are happy with the preview.
7. AEOHelper will make the Markdown available at a clean `/index.md` endpoint and add a discovery link to the original page's HTML head.
8. Optionally configure the `llms.txt` manager to organise approved Markdown pages into sections with custom titles and descriptions.
9. Optionally enable Request Activity to monitor requests to your Markdown and `llms.txt` endpoints.

PHP DOM/XML is required.

If you use page caching or a CDN, clear relevant caches after publishing, withdrawing or changing Markdown discovery links.

== Frequently Asked Questions ==

= What is the benefit of linking a Markdown version from my page header? =

Normal web pages often contain navigation, styling, scripts, page-builder markup and other HTML that is useful for browsers but not necessary when an automated system only needs the page's content.

AEOHelper creates a cleaner Markdown representation and adds an alternate discovery link to it from the original page's HTML head. Compatible crawlers and AI systems can therefore discover a simpler version containing the useful headings, paragraphs, links, lists, tables and other content.

This can reduce unnecessary markup and make the important content easier to extract and process. It does not guarantee that an AI provider will crawl, index, cite or recommend the page, because each provider decides how it retrieves and uses web content.

= Does this replace my normal web page? =

No. The original HTML remains unchanged. AEOHelper publishes a separate Markdown response and adds a discovery link from approved HTML pages to their Markdown version.

= Where is the Markdown version published? =

Approved content is published at a clean permalink-based Markdown endpoint, for example:

`example.com/your-page/index.md`

The exact URL follows the original WordPress permalink.

= Can I review the Markdown before it is published? =

Yes. Manual review and approval before first publication is a core part of the plugin. You can inspect the Markdown preview before making it publicly available.

= Can I control what appears in the Markdown version? =

Yes. You can exclude selected content, add Markdown-only context and opt selected visual layouts into structured Markdown table conversion.

AEOHelper provides the following attributes:

* `data-aeohelper-exclude`
* `data-aeohelper-context`
* `data-aeohelper-table`

These controls affect the generated Markdown without changing the page shown to normal website visitors.

= Is content sent to an external AI service? =

No. Conversion happens on the WordPress site. The plugin makes a same-site logged-out HTTP request to the selected public URL so it can extract the rendered HTML.

No external AI service is required for core functionality.

= Does this guarantee AI citations or recommendations? =

No. AEOHelper provides a clean, discoverable alternative representation of your content. Crawling, indexing, retrieval, recommendations and citations remain decisions made by individual providers.

= Can it manage llms.txt? =

Yes, optionally.

The `llms.txt` manager is off by default. You can include approved Markdown pages, organise them into sections, control their order and use custom titles and descriptions.

The plugin refuses first-time activation of its `llms.txt` manager when an existing physical file, responding endpoint or known Rank Math `llms.txt` module is detected, helping avoid conflicts.

= Does Request Activity verify genuine AI crawlers? =

No. Request Activity categorises the user-agent string supplied with a request. User-agent names can be spoofed.

Use server or CDN logs and provider IP-verification documentation when verified crawler identity is required.

= What information does Request Activity store? =

When explicitly enabled, Request Activity stores the request time, endpoint, associated post ID, method, response status and general user-agent category in the local WordPress database.

It does not store IP addresses, cookies or referrers and does not send the records externally.

Identical requests are collapsed into 15-minute observations and only the latest 10,000 records are retained, so Request Activity is not intended to be exact traffic analytics.

= What happens when the original page changes? =

AEOHelper supports manual, draft-only and automatic update handling for previously approved Markdown.

This lets you decide whether changes to the source content should require another review or be reflected automatically according to your chosen settings.

= Will AEOHelper publish drafts, password-protected or noindex content? =

AEOHelper includes safeguards for drafts, password-protected content, known noindex settings and common account routes.

Always review your selected content and generated Markdown before publication.

== Privacy ==

AEOHelper does not send telemetry or site content to any external service.

When optional Request Activity is enabled, endpoint activity is stored only in the local WordPress database for the selected retention period. Administrators can clear it at any time.

Deleting the plugin removes its settings, generated documents and request table.

The plugin includes a suggested privacy-policy paragraph in WordPress Privacy settings.

== External services ==

No external service is required for core functionality.

Conversion, previews, approved Markdown and optional Request Activity are handled locally by WordPress, except that preview generation makes a same-site public HTTP request to the page being converted.

== Screenshots ==

1. AEOHelper overview showing published Markdown, recent request volume, llms.txt status and the latest Markdown or llms.txt request.
2. Manage WordPress Pages and Posts, view publication status and open per-page Markdown controls.
3. Generate a Markdown preview, review the extracted content and use extraction controls before publishing.
4. Monitor local requests to Markdown and llms.txt endpoints, including crawler category, request method and HTTP response status.
5. Configure the optional llms.txt manager, including site information, section ordering and automatically maintained approved Markdown pages.
6. Choose the publishing scope and control what happens when previously approved source content changes.

== Changelog ==

= 0.5.3 =

* Renamed the plugin to AEOHelper - Markdown Publisher with the final WordPress.org identity and slug.
* Updated the stable release metadata for WordPress.org.
* Added optional `llms.txt` section ordering and per-page ordering within each section.
* Improved the `llms.txt` section-order placeholder so multi-line examples display correctly in the admin.
* Added a clear notice when `llms.txt` metadata is configured before Markdown has been published.
* Removed standalone decorative `#` symbols from generated Markdown while preserving meaningful hashes inside normal text.
* Added an admin-page-only optional ZireAI information card while keeping AEOHelper fully independent.
* Hardened administrator actions with nonce, capability, task allow-list and per-post permission checks.
* Added AEOHelper data attributes while retaining legacy attribute support for existing installations.
* Updated release wording and metadata for the WordPress.org submission candidate.

= 0.4.1 =

* Added optional per-page `llms.txt` link-title overrides.
* Added automatic title and description fallbacks from rendered SEO metadata, Rank Math, Yoast and WordPress content.
* Manual `llms.txt` title and description fields take priority over automatic metadata.
* Decoded HTML entities before emitting `llms.txt` link titles and descriptions.

= 0.4.0 =

* Added Markdown-only section context through `data-aeohelper-context`.
* Added a compact admin reference for context, exclusion and visual-table attributes.
* Kept HTML headings containing line breaks on one Markdown heading line.
* Removed decorative headings and improved duplicate-H1 matching.
* Fixed malformed nested bold and italic output.
* Added manual, draft-only and automatic previously-approved Markdown update modes.
* Added background refresh status and clarified automatic `llms.txt` listing.

= 0.3.1 =

* Added opt-in conversion of div-based visual grids into Markdown tables.
* Converted standalone comparison checkmarks and dashes into clear included/not-included values.
* Added visual-grid instructions to the Extraction controls.
* Added automatic one-time rewrite-rule refreshing after plugin updates.

= 0.3.0 =

* Added clean permalink-based `/index.md` routes.
* Added permanent redirects from legacy `zire_ai_md` query URLs.
* Added HTTP canonical Link headers from Markdown responses to their original HTML pages.
* Added alternate Markdown and `llms.txt` discovery links to eligible HTML pages.
* Limited X-Robots-Tag noindex to error responses.

= 0.2.0 =

* Added an Overview dashboard and reorganised administration navigation.
* Added optional local Request Activity with retention and clearing controls.
* Added repeat-request deduplication and a 10,000-record activity cap.
* Added per-page last-request information.
* Added conversion diagnostics to previews.
* Added exact duplicate-H1 removal.
* Added safe handling for links that wrap complete content cards.
* Prevented empty strong and emphasis markers in Markdown.
* Added WordPress privacy-policy text and directory readme.

= 0.1.4 =

* Converted native disclosure and FAQ blocks into clean Markdown questions and answers.
* Removed common decoration-only disclosure controls.

= 0.1.3 =

* Added per-page CSS selector exclusions and manual `data-aeohelper-exclude` support.

== Upgrade Notice ==

= 0.5.3 =

Adds the final AEOHelper WordPress.org release, reviewed Markdown publishing, page-header discovery links, optional `llms.txt` management, context controls and local request monitoring.
