Problem/Motivation

The <link rel="alternate" type="text/markdown"> meta tag added by markdownify_page_attachments() always uses the .md extension format (e.g. /node/1.md).
This URL format may not work in all server environments — for example, certain nginx configurations block or do not pass through requests ending in .md.
The module itself already supports multiple URL formats to access Markdown content (.md extension, _format=markdown query parameter, and /markdownify/ prefix routes), but there is no way to control which format is used in the advertised alternate link.

Steps to reproduce

1. Install and configure the markdownify module.
2. Visit a supported entity page (e.g. a node).
3. Inspect the HTML - the <link rel="alternate" type="text/markdown"> always points to a .md URL.
4. On servers where .md URLs are blocked (e.g. by nginx rules), the advertised link returns a 403 or 404, even though ?_format=markdown works fine.

Proposed resolution

Add a "Alternate link URL format" configuration option to the markdownify settings form (/admin/config/services/markdownify) that lets site administrators choose which URL format is used in the
meta tag:

- .md extension — e.g. /node/1.md (current behavior, remains the default)
- Query parameter — e.g. /node/1?_format=markdown
- Markdownify prefix — e.g. /markdownify/node/1

All three formats remain functional for accessing Markdown content regardless of this setting; it only controls which one is advertised in the HTML head.

Remaining tasks

- Review the patch.
- Decide whether additional URL formats should be supported (e.g. path alias variants via markdownify_path).
- Add test coverage for the new configuration option.

User interface changes

A new "Alternate link URL format" radio button group is added to the markdownify settings form at /admin/config/services/markdownify, with three options:
.md extension, Query parameter, and Markdownify prefix.

API changes

None.

Data model changes

A new link_format string key is added to the markdownify.settings config object. Accepted values: md_extension (default), query_parameter, markdownify_prefix.

Comments

criz created an issue. See original summary.

criz’s picture

christophweber’s picture

This is an interesting one, and I agree we can fix it as proposed. But before that I want to fix https://www.drupal.org/project/markdownify/issues/3590402 to enable all request formats on Views pages. Once we merge that MR, could you create an MR based on the latest dev release and post it?
I'd also like to pay attention to the admin page and strongly encourage people to fix their NGINX config it at all possible. The .md extension is becoming a universal way for requesting raw MD as part of the llms.txt propoal/standard, and "breaking" this because it is less work or easier is undesirable,