Skip to content

Troubleshooting and FAQ

Troubleshooting

robots.txt has none of the directives. The static robots.txt file is still in the docroot, so the web server answers before Drupal. Delete it and keep the composer scaffold from restoring it; see Installation. Without the RobotsTxt module nothing is written to robots.txt at all; the settings form and the status report say so.

A .md URL is a 404. One of these:

  • the entity type, bundle or language is not exposed in Markdownify's settings (the Declared signals page shows which bundles are);
  • the page is not an entity and agent_surface_fallback is not enabled;
  • the page is an administrative route, which never converts;
  • the alias form (/recipes/oatmeal.md) is used without Markdownify Path.

A .md URL is a 403. The HTML page is a 403 for the same visitor. The Markdown follows the HTML's access exactly.

The status report warns about unreviewed defaults. Review the settings form and save it once. That is the acknowledgement.

A matched agent gets HTML. Behind a CDN, header and user-agent negotiation only take effect on cache misses. Point agents at the .md URL, which every HTML page advertises in a Link header and a <link rel="alternate"> element.

Markdown shows up where HTML was expected behind a CDN. It should not: negotiated Markdown is sent with Cache-Control: private, no-store. Check that the CDN honours private.

PHP warnings from Markdownify Metadata on every .md request. With Schema.org Metatag installed, Markdownify Metadata raises two warnings per request; the front matter is still correct. This is Markdownify #3619685.

Views pages are 500 as .md with markdownify_views. On Drupal 11.4 Markdownify's Views controller skips its parent constructor. Agent Surface does not depend on markdownify_views; use agent_surface_fallback for Views pages instead.

The request report shows no data. Check that Enable the request log is on, and that the requests are for Markdown or come from a matched user agent; plain HTML requests are not logged.

FAQ

Does this improve search rankings? No. Search engines do not use Markdown alternates or llms.txt. What it does is make responses smaller for agents that ask for Markdown, answer unchanged pages with a 304, and state usage terms consistently.

Which agents get Markdown without asking? Those whose User-Agent contains one of the patterns under Serving Markdown on the settings form. The list needs maintenance as new agents appear. Search engine crawlers do not belong on it.

What does "Unstated" mean? Nothing is emitted for that category. Under AIPREF, Content Signals and RSL, saying nothing is different from saying yes.

Can one page differ from its content type? No. Overrides are per bundle, and path-scoped rules per bundle prefix. Per-page rules would grow robots.txt without bound.

Is a user agent match a proof of identity? No. It is a substring test, as robots.txt parsers do with product tokens. The Signature-Agent header (Web Bot Auth) is logged when present but not verified.

Is any personal data logged? No IP addresses, cookies or session identifiers. User profiles are not exposed as Markdown unless Expose user profiles is turned on.