The open convention behind WP Markdown Endpoint: deterministic machine-readable twins of every canonical article, discoverable without proprietary APIs. Identified in machine documents as wp-markdown-endpoint/1. Also available as clean Markdown — of course.
Status: Published 9 August 2026 by WP Markdown Endpoint (Valley PC). This is an open publishing convention, identified in machine documents as wp-markdown-endpoint/1. It is not an industry standard and does not claim recognition by any AI vendor. Anyone may implement it; this document is also available as Markdown at /agent-publishing-spec.md.
WP Markdown Endpoint provides a simple, deterministic way for websites to expose clean, machine-readable versions of published content to AI assistants, LLMs, autonomous agents, research systems and other automated consumers.
The specification is designed around one principle:
Publish once. Serve humans and machines from the same canonical content.
A normal WordPress article remains the canonical page for human readers and search engines, while machine-readable representations are made available alongside it.
For any published article or page:
Human-readable canonical URL:
https://example.com/article-slug/
Markdown representation:
https://example.com/article-slug.md
JSON representation:
https://example.com/article-slug.json
This URL pattern is deterministic.
An AI agent that discovers the canonical article URL can derive the machine-readable version without requiring an API key, separate API documentation or knowledge of the underlying WordPress installation.
The normal WordPress page remains the canonical source. The HTML page should continue to serve normal visitors, browsers, search engines and existing integrations. The machine-readable representations must not replace the canonical page.
Where appropriate, the canonical HTML page should include normal metadata such as:
Each eligible published page should expose a Markdown version at /{slug}.md.
Recommended response header:
Content-Type: text/markdown; charset=utf-8
The Markdown representation should contain the useful content of the page without website presentation markup. It should normally exclude:
The objective is clean, token-efficient content that an AI system can consume directly.
Markdown documents may include YAML front matter.
Recommended structure:
--- title: "Article title" publisher: "Example Publisher" author: "Author Name" published: "2026-08-09T12:00:00+01:00" modified: "2026-08-09T13:30:00+01:00" canonical: "https://example.com/article-slug/" category: "Technology" language: "en-GB" format: "news" ---
Only metadata that genuinely exists should be included. Implementations must not fabricate missing authors, dates, categories or other values.
The canonical URL should always refer to the normal human-readable page.
A recommended Markdown article structure is:
# Article title Article introduction. ## Section heading Article content. [Source or related link](https://example.com/)
The output should preserve meaningful headings, paragraphs, lists, quotations, links, tables where practical and image references where useful. Decorative or layout-only content should be removed. All URLs should be absolute — agents may process a document without retaining its base URL.
Each eligible published page may also expose a structured JSON representation at /{slug}.json.
Recommended response header:
Content-Type: application/json; charset=utf-8
Recommended minimum structure:
{
"title": "Article title",
"publisher": "Example Publisher",
"author": "Author Name",
"published": "2026-08-09T12:00:00+01:00",
"modified": "2026-08-09T13:30:00+01:00",
"canonical_url": "https://example.com/article-slug/",
"markdown_url": "https://example.com/article-slug.md",
"json_url": "https://example.com/article-slug.json",
"language": "en-GB",
"content": "Article content..."
}
Additional fields may include the post ID, excerpt, categories, tags, featured image, source URLs, content type or publication section.
Private WordPress metadata or administrative information must never be exposed.
The canonical HTML page should advertise available machine-readable alternatives.
Recommended HTML:
<link rel="alternate" type="text/markdown" href="https://example.com/article-slug.md"> <link rel="alternate" type="application/json" href="https://example.com/article-slug.json">
This allows agents and machine clients to discover the alternative formats without prior knowledge of the URL convention.
Implementations may also advertise alternative representations using HTTP Link headers:
Link: <https://example.com/article-slug.md>; rel="alternate"; type="text/markdown" Link: <https://example.com/article-slug.json>; rel="alternate"; type="application/json"
This allows machine clients to discover available representations without parsing the HTML document.
Sites implementing the specification should provide /llms.txt.
The file should briefly describe the website and tell AI systems how to access machine-readable content.
Example:
# Example Publisher
Example Publisher publishes business and technology news.
## Machine-readable content
Canonical HTML:
https://example.com/{article-slug}/
Markdown:
https://example.com/{article-slug}.md
JSON:
https://example.com/{article-slug}.json
For AI and LLM retrieval, prefer the Markdown representation where available.
## Latest content
AI feed:
https://example.com/feed/ai.json
Markdown index:
https://example.com/markdown-sitemap.md
Sitemap:
https://example.com/sitemap.xml
The file should remain concise and factual — a discovery document, not an index.
Sites implementing the specification can expose their latest published content through a dedicated AI-oriented feed using the established JSON Feed 1.1 format. Rather than creating a proprietary feed protocol, the specification uses JSON Feed as the foundation for content discovery.
Recommended endpoint: /feed/ai/, returning:
Content-Type: application/feed+json; charset=utf-8
A compatibility twin should be provided at /feed/ai.json, serving the identical body as:
Content-Type: application/json; charset=utf-8
The twin exists because some JSON parsers and HTTP clients reject the application/feed+json media type — implementations must not serve feed+json on both URLs.
The purpose of the AI feed is to give LLMs, autonomous agents, research systems and other machine consumers a lightweight mechanism for discovering recently published content without repeatedly crawling the entire website. Each item identifies the canonical article and, where available, its machine-readable representations — carried in a _machine extension object, following JSON Feed's underscore convention for custom extensions:
{
"version": "https://jsonfeed.org/version/1.1",
"title": "Example Publisher",
"home_page_url": "https://example.com/",
"feed_url": "https://example.com/feed/ai.json",
"language": "en-GB",
"items": [
{
"id": "https://example.com/company-announces-results/",
"url": "https://example.com/company-announces-results/",
"title": "Company announces results",
"date_published": "2026-08-09T12:00:00+01:00",
"date_modified": "2026-08-09T13:30:00+01:00",
"summary": "Short article summary",
"authors": [{ "name": "Author Name" }],
"tags": ["Technology"],
"_machine": {
"markdown_url": "https://example.com/company-announces-results.md",
"json_url": "https://example.com/company-announces-results.json",
"category": "Technology"
}
}
]
}
Every item should carry a summary — the hand-written excerpt or a short generated one — so an agent can triage the feed without fetching articles. The feed should remain compact: its purpose is discovery, not duplication of the entire website.
The preferred retrieval flow once an agent identifies an article of interest:
AI Feed → Markdown article → Canonical citation
This separates three responsibilities:
Discovery: JSON Feed 1.1
Efficient content retrieval: Markdown
Canonical attribution and human access: HTML
The AI feed complements rather than replaces conventional RSS, XML sitemaps or other existing WordPress discovery mechanisms.
Sites may expose a complete machine-readable index of their available Markdown documents at:
/markdown-sitemap.md
Recommended response header:
Content-Type: text/markdown; charset=utf-8
Recommended structure — one link line per document, newest first, with its publication date:
# Example Publisher — Markdown index 312 documents. Each link serves clean Markdown. - [Company announces results](https://example.com/company-announces-results.md) — 2026-08-09 - [Quarterly report published](https://example.com/quarterly-report-published.md) — 2026-08-08
This completes the separation of discovery responsibilities: llms.txt stays a concise instruction document, the AI feed carries what is new, and the Markdown sitemap enumerates the full corpus. An agent performing a complete site ingest reads the sitemap once rather than crawling.
The sitemap must apply the same publication-state checks as every other machine endpoint — only published, public, non-excluded content may appear — and it must update automatically as content is published, updated or removed.
Sites may expose a compact machine-readable description of their whole content interface at:
/.well-known/ai-content.json
Recommended structure:
{
"convention": "wp-markdown-endpoint/1",
"publisher": "Example Publisher",
"canonical": "https://example.com/",
"language": "en-GB",
"content": {
"html": "https://example.com/{slug}/",
"markdown": "https://example.com/{slug}.md",
"json": "https://example.com/{slug}.json"
},
"discovery": {
"llms": "https://example.com/llms.txt",
"feed": "https://example.com/feed/ai.json",
"markdown_sitemap": "https://example.com/markdown-sitemap.md",
"sitemap": "https://example.com/sitemap.xml"
},
"preferred_agent_format": "markdown"
}
The convention field identifies which version of this specification the site implements — wp-markdown-endpoint/1 corresponds to this document. The /1 is the protocol major version: it changes only on a breaking change to the convention. Optional additions do not change it, and never make an existing v1 implementation non-conformant. Implementation software versions move independently of the protocol version.
The manifest must list only endpoints that are actually enabled and must not imply recognition by any AI vendor.
A conforming AI agent can follow this retrieval process:
rel="alternate" declarations or HTTP Link headers..md representation where available..json when structured metadata is required./feed/ai.json to discover recently published content, and /markdown-sitemap.md to enumerate the full corpus./llms.txt or /.well-known/ai-content.json for site-level discovery.The canonical HTML article must remain the authoritative public URL. Machine-readable variants should clearly reference the canonical page — canonical: in Markdown front matter, canonical_url in JSON.
Implementations should avoid presenting .md or .json representations as separate editorial publications. They are alternate representations of the same underlying content.
Machine-readable representations are intended primarily for machine consumption. Publishers should determine whether .md or .json URLs should be indexed by conventional search engines based on their own SEO strategy. The important requirement is that the canonical human-readable article remains clearly identified as the primary URL.
Reference implementation note: WP Markdown Endpoint sends X-Robots-Tag: noindex, follow plus a Link: rel="canonical" header on every machine response, so the machine twins can never compete with the canonical article in search. The front-matter canonical: field alone is invisible to search engines — the HTTP header is the signal that matters.
Sites should review robots.txt to ensure legitimate crawlers are not unintentionally prevented from accessing the machine-readable layer: .md pages, .json pages, /llms.txt, /feed/ai.json and normal sitemaps.
Crawler access remains a publisher decision. The specification does not require publishers to allow every crawler or every AI provider. Existing security, rate-limiting and crawler policies should be respected.
Machine-readable endpoints must only expose content that is already intended for public publication.
Implementations must not expose:
Publication-state checks must be applied independently to the machine-readable endpoints.
Implementations should treat .md and .json endpoints as public application endpoints:
Machine-readable responses should be inexpensive to serve. Implementations should use appropriate caching, and cached representations should be invalidated when the source content is published, updated, deleted, moved to draft or made private.
The machine-readable response must not become permanently stale relative to the canonical article. ETag and Last-Modified headers with conditional-request support let agents and CDNs revalidate cheaply.
The machine-readable content should derive directly from the underlying WordPress post or page. Publishers should not need to maintain separate Markdown or JSON documents manually.
Recommended model — one source of truth: the WordPress content — from which HTML, Markdown, JSON, feed entries and discovery metadata are all generated automatically. This avoids version drift between human and machine-readable content.
Implementations must not alter existing public permalink behaviour. Normal WordPress URLs should continue functioning exactly as before.
The specification should coexist with the WordPress REST API, RSS feeds, XML sitemaps, SEO plugins, caching plugins, CDN services, analytics systems and standard browser traffic.
A full implementation may expose:
/{slug}/
Canonical human-readable article
/{slug}.md
Agent-optimised Markdown
/{slug}.json
Structured machine-readable article
/llms.txt
AI discovery and instructions
/.well-known/ai-content.json
Machine-readable interface manifest
/markdown-sitemap.md
Markdown document corpus index
/feed/ai/
JSON Feed 1.1 latest-content discovery
/feed/ai.json
JSON-compatible feed twin
/sitemap.xml
Conventional website discovery
Each endpoint answers a different question:
llms.txt — tells an agent what the site provides.well-known/ai-content.json — tells software how the machine interface worksmarkdown-sitemap.md — tells an agent what documents are availablefeed/ai/ — tells an agent what's new{slug}.md — provides the content{slug}.json — provides the structured data{slug}/ — provides the canonical sourceOne of the core design goals is simplicity. Given https://example.com/article-slug/, an agent can infer https://example.com/article-slug.md and https://example.com/article-slug.json.
This enables machine-readable retrieval without proprietary APIs, authentication or platform-specific SDKs.
Markdown preserves meaningful document structure while removing most presentational overhead. Compared with a full web page, it significantly reduces HTML boilerplate, navigation content, styling markup, script content, irrelevant DOM structure, token consumption and extraction complexity — while retaining headings, paragraphs, lists, links, quotations and tables.
Markdown is optimised for document consumption. JSON is useful when an agent or integration needs explicit structured fields: content ingestion, indexing, semantic search, RAG pipelines, metadata extraction, news monitoring, content automation and research agents.
The two formats are complementary.
Simple discovery — an agent should find machine-readable content without proprietary documentation.
Deterministic URLs — machine formats should be predictable from the canonical URL.
Clean content — only useful editorial content should be returned.
Low token overhead — AI systems should not process unnecessary presentation markup.
Structured metadata — publication information should be explicit where available.
Canonical attribution — the original article must remain easy to identify and cite.
Open access — no proprietary APIs or SDKs required.
Security — private or unpublished content must never leak through alternate representations.
Backward compatibility — existing websites and WordPress behaviour remain unaffected.
Canonical article: https://example.com/company-announces-results/
Markdown: https://example.com/company-announces-results.md
JSON: https://example.com/company-announces-results.json
Discovery: https://example.com/llms.txt and https://example.com/.well-known/ai-content.json
Latest-content feed: https://example.com/feed/ai.json
An AI agent can therefore move from discovery to retrieval using standard web requests alone.
WP Markdown Endpoint implements this specification for WordPress. Publishers keep their normal WordPress editorial workflow while machine-readable representations are exposed automatically.
No separate CMS. No duplicate publishing workflow. No proprietary agent API.
The Agent Publishing Specification is intentionally simple.
It does not attempt to replace HTML, RSS, JSON-LD, XML sitemaps or the WordPress REST API. It complements them. HTML remains the format for browsers. Structured data remains useful for search engines. Feeds remain useful for syndication. Markdown and structured JSON give AI agents a cleaner way to retrieve the underlying published content.
The result is a website that serves both audiences from the same source:
Humans read the website.
Agents read the content.
Publishers manage only one article.