# Markdown alternates: field kit (The GEO Lab, Version 2.5.2)
# Offer a clean Markdown copy of important pages and point to it openly.
# Same facts as the HTML page. The canonical header signals the HTML page as the preferred URL;
# search engines still choose the canonical themselves (Google: rel="canonical" is a strong signal, not a guarantee).
# Standard: llms.txt v2 (llmstxt.org, Aug. 10, 2026). Replace example.com with your domain.
# Use one or more of options 1a, 1b and 1c. Every option needs the headers in step 2.

## 1a. Link element in the <head> of the HTML page (https://example.com/pricing)
<link rel="alternate" type="text/markdown" href="https://example.com/pricing.md">
<link rel="describedby" href="https://example.com/llms.txt">

## 1b. Or the same signal as an HTTP response header on the HTML page (works for any file type)
Link: <https://example.com/pricing.md>; rel="alternate"; type="text/markdown"

## 1c. Or content negotiation: same URL, Markdown when the client asks for it
# Send Vary: Accept on BOTH the HTML and the Markdown response, so caches keep them apart.
# Cloudflare: turn on "Markdown for Agents" for the zone (changelog, Feb. 12, 2026).
# nginx: a LIMITED DEMO, tested with nginx 1.24 (test your own setup before use).
# It serves Markdown only when the whole Accept header is text/markdown, optionally with a charset.
# Any mixed header (for example "text/markdown, text/html;q=0.9") gets HTML. Real negotiation weighs
# q-values (RFC 9110, section 12.4.2: q=0 means "not acceptable"); do that in your application or a
# tested module, not with a pattern match. A bare "~*text/markdown" would also match q=0 and lookalikes.
map $http_accept $want_md {
    default 0;
    "~*^\s*text/markdown\s*(;\s*charset=[\w-]+\s*)?$" 1;
}
server {
    location = /pricing {
        add_header Vary Accept always;
        if ($want_md) { rewrite ^ /pricing.md last; }
        try_files /pricing.html =404;
    }
    location ~ \.md$ {
        types { } default_type "text/markdown; charset=utf-8";
        add_header Vary Accept always;
        add_header Link '<https://example.com/pricing>; rel="canonical"' always;
    }
}
# (Set the canonical per page in production; the line above is for the /pricing example.)

## 2. Headers on the Markdown copy itself (https://example.com/pricing.md, or the negotiated reply)
Content-Type: text/markdown; charset=utf-8
Link: <https://example.com/pricing>; rel="canonical"

## 3. Test the option you implemented

# Option 1a: is the alternate link in the delivered HTML head?
curl -s https://example.com/pricing | grep -io '<link[^>]*text/markdown[^>]*>'

# Option 1b: is the alternate Link header on the HTML page?
curl -sI https://example.com/pricing | grep -i '^link:'

# Options 1a and 1b: request the .md copy directly.
# Expect HTTP 200, Content-Type: text/markdown and the canonical Link header back to the HTML page.
curl -sI https://example.com/pricing.md | grep -iE '^HTTP|^content-type|^link'
curl -s  https://example.com/pricing.md | head -20

# Option 1c only: ask the page URL for Markdown.
# Accept: text/markdown -> Markdown. Expect Content-Type: text/markdown, Vary: Accept and the canonical Link header.
curl -sI -H 'Accept: text/markdown' https://example.com/pricing | grep -iE '^content-type|^vary|^link'
curl -s  -H 'Accept: text/markdown' https://example.com/pricing | head -20
# These must still get HTML, with Vary: Accept: q=0 means "not acceptable", and a lookalike type is not a match.
curl -sI -H 'Accept: text/html, text/markdown;q=0' https://example.com/pricing | grep -iE '^content-type|^vary'
curl -sI -H 'Accept: text/markdownish' https://example.com/pricing | grep -iE '^content-type|^vary'
# ...and confirm a plain request still gets HTML, also with Vary: Accept.
curl -sI https://example.com/pricing | grep -iE '^content-type|^vary'
# A missing expected line needs investigation: check redirects, the status, the GET response and the
# actual Link/header value before deciding the feature is absent.

## 4. Measure it (server or CDN logs)
# Count requests for *.md URLs and requests whose Accept header contains text/markdown, by user agent.
# Example (combined log format with the Accept header logged as the last field):
#   grep -E '\.md |text/markdown' access.log | awk -F'"' '{print $6}' | sort | uniq -c | sort -rn

## Rules
# - Never choose the response by user agent. Anyone who asks gets the same Markdown.
# - Regenerate the .md whenever the HTML facts change (best: build both from one source).
# - Keep navigation out, keep facts, numbers, dates, author and source links in.
# - The canonical annotation signals your preferred URL; it does not guarantee which URL is indexed or shown.
# - This helps AI agents and tools read the page. It is not a Google ranking or citation signal:
#   Google says Search does not use Markdown or llms.txt (AI optimization guide, July 2026).
