=== MTM HTML to Markdown ===
Contributors: mtmplugins
Donate link: https://movingtrafficmedia.com/
Tags: markdown, html, export, caching, mtm
Requires at least: 5.0
Tested up to: 6.9
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Converts any WordPress page or post to Markdown at a .md.txt URL with caching and YAML headers.

== Description ==

Serve cached Markdown versions of WordPress URLs at .md.txt with YAML frontmatter. No theme changes required.

When a visitor requests a URL ending in `.md.txt`, the plugin:
1. loads the page HTML,
2. extracts the primary content (default selector: `main`),
3. converts HTML to Markdown,
4. prepends YAML frontmatter (metadata),
5. returns the result with short-term caching.

This keeps your normal site unchanged while exposing a clean Markdown output for tooling, archiving, and AI-friendly documentation workflows.

Key features include:

* `.md.txt` endpoint for pages, posts, and public custom post types
* YAML frontmatter headers for structured metadata (title, slug, canonical URL, generated time)
* HTML → Markdown conversion via League HTML to Markdown
* Builder-noise cleanup for common wrappers (Divi, Elementor, block markup)
* Configurable selector (default: `main`)
* Cached output to reduce repeated conversions
* Optional "Force Update" from the admin panel for refreshing the Markdown cache.

= LLMs.txt / AI Documentation Workflows =

Many teams maintain a `/llms.txt` index file that links to “detail” Markdown pages for fast AI ingestion and navigation.
This plugin can act as the “detail page generator” by making each page available as Markdown via a stable URL.

Typical pattern:
- `/llms.txt` lists key pages (human curated)
- each entry links to the corresponding `.md.txt` URL for full content

(If you publish `/llms.txt`, confirm it only includes URLs you intend to expose publicly.)

= Example Output =
---
plugin: "MTM HTML to Markdown"
source_url: "https://example.com/sample-page/"
generated_at: "2026-01-08T13:00:00-05:00"
slug: "sample-page"
---
# Sample Page
(Body converted to Markdown…)

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/`.
2. Activate via the WordPress Plugins screen.
3. Visit Settings → MTM HTML to Markdown to adjust the content selector (default: `main`).
4. Ensure “pretty permalinks” are enabled (Settings → Permalinks).
5. Append `.md.txt` to any public URL: https://example.com/sample-page.md.txt

== Frequently Asked Questions ==

= How do I generate the Markdown version of a page? =
Simply append `.md.txt` to the end of any page, post, or custom post type URL.  
Example: `https://example.com/sample-page.md.txt`

= How do I generate the Markdown version of the homepage? =
For the homepage, you need to use the `home` slug in the URL.  
Example: `https://example.com/home.md.txt`  
Accessing `https://example.com/.md.txt` or `https://example.com/index.md.txt` will not work unless configured otherwise.

= Can I select a specific part of the page for conversion? =
Yes. Go to **Settings → MTM HTML to Markdown** and enter the HTML tag or ID you want to extract (default: `main`).

= Does this plugin work with page builders like Divi or Elementor? =
In most cases, yes. The conversion uses the rendered HTML output and includes cleanup to reduce common wrapper noise.
Highly dynamic or JS-rendered fragments may not appear in server-generated HTML.

= How long is the Markdown cached? =
By default, converted Markdown is cached for **15 minutes**.  

To force a refresh of the Markdown cache for a page, append the following parameters to the `.md.txt` URL: ?force_update=1&mtm_md_nonce=<nonce>

For example: https://example.com/sample-page.md.txt?force_update=1&mtm_md_nonce=<nonce>

If you are unsure about the nonce, you can use the **"Force Update Markdown" button** in the plugin settings page. Enter the page slug, and it will open the correct URL in a new tab with the nonce automatically included.

= Does this change my site’s normal pages or SEO? =
Normal URLs remain unchanged. Markdown is only served when `.md.txt` is requested.

= Does the plugin track users or send data to external services? =
No. The plugin does not send page content or visitor data to external servers.

== Troubleshooting ==

= I get a 404 on .md.txt URLs =
Confirm pretty permalinks are enabled, then re-save Settings → Permalinks to flush rewrite rules.
If a caching layer/CDN is in front of the site, purge cache for the `.md.txt` path.

= Output is missing content =
If your theme does not use a <main> element, change the selector to match the real content container (e.g., #content).

== Screenshots ==

1. Settings screen showing selector configuration
2. Example Markdown output with YAML frontmatter

== Changelog ==

= 1.0.0 =
* First public release
* Converts pages, posts, and custom post types to Markdown
* Handles page builder HTML cleanup
* Adds YAML headers with plugin info, URL, slug, and generation date
* Short-term caching and optional force refresh
* Settings page to configure HTML selector
* Added Force Update option via admin button or URL with nonce

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrades yet.

== Credits ==

Developed by Moving Traffic Media & YSC.  
Uses [League HTML to Markdown](https://github.com/thephpleague/html-to-markdown) under MIT license.

== License ==

This program is free software: you can redistribute it and/or modify it under the terms of the **GNU General Public License v2 or later**.  
See the full license at [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html).