Guide

Markdown for Agents architecture

URL interception, conversion pipeline, discovery, and integrations.

Request path

  1. Rewrites — parse_request intercepts paths ending in .md or /markdown, resolves the post with url_to_postid(), and serves Markdown. Optional ?markdown=true on the canonical URL also serves Markdown.
  2. Discovery — wp_head injects rel="alternate" tags for both endpoints; /llms.txt is registered as its own rewrite.
  3. Robots — robots_txt injects a Content-Signal: directive (and an agent-index comment referencing /llms.txt).
  4. Accept negotiation — when PRC_MARKDOWN_FOR_AGENTS_ENABLE_ACCEPT_NEGOTIATION is true, template_redirect can hijack responses for Accept: text/markdown. Disabled by default (VIP edge cache; Linear PRC-466).

Markdown_Response::serve() builds YAML frontmatter (Frontmatter::build()), converts blocks (Markdown_Converter), sets headers (Content-Type: text/markdown, Vary: Accept, X-Markdown-Tokens, Content-Signal, X-Robots-Tag: noindex), and exits.

Flow

Markdown serve path

4 relationships
Explicit URL suffixes own the Markdown response.

Conversion

The converter walks the parsed block tree:

  • Registered callbacks in Block_Markdown_Registry produce Markdown for that block name
  • Container blocks recurse into inner blocks
  • Everything else falls through to render_block() → HTML_To_Markdown_Converter

Post types opt in with add_post_type_support( $type, 'prc-markdown-for-agents' ).

Soft integrations

Guarded integrations enrich frontmatter or body when companion plugins are active:

IntegrationEffect
prc-staff-bylinesauthors frontmatter
prc-datasetsdatasets frontmatter
prc-pdf-extractionPDF extraction URL in frontmatter
prc-report-packageTOC / next-chapter links in the body

Settings REST (admin UI)

GET / POST /wp-json/prc-markdown-for-agents/v1/settings requires manage_options. These routes power Settings → Markdown for Agents and are not a public agent contract. Agents should use .md, /markdown, and /llms.txt.

Extension hooks

Primary extension points (full list in the plugin README):

  • prc_markdown_for_agents_register_block_callbacks — register block Markdown callbacks
  • prc_markdown_for_agents_frontmatter — mutate frontmatter arrays
  • prc_markdown_for_agents_after_markdown — append or transform body Markdown
  • prc_markdown_for_agents_pre_markdown — short-circuit conversion with pre-built Markdown

Was this helpful?