Replace llms.txt with Accept: text/markdown content negotiation

nginx.conf

@@ -35,20 +35,48 @@ http {
     default "";
   }
 
+  # Content negotiation: clients asking for markdown (Claude sends
+  # `Accept: text/markdown`) get the llms.txt rendition of the same URL.
+  map $http_accept $negotiated_index {
+    ~*text/markdown llms.txt;
+    default index.html;
+  }
+
   server {
     listen 8080;
     access_log /dev/stdout;
     root /app/public;
 
+    add_header Vary Accept;
+
     location ~ ^/openapi(.*)\.json$ {
       add_header Access-Control-Allow-Origin *;
+      add_header Vary Accept;
+    }
+
+    # bin/compress.js writes a .br/.gz sibling for every file. gzip_static and
+    # brotli_static read those from disk while serving the original URL, so the
+    # siblings need no URL of their own. A genuine .br/.gz download would need
+    # an exception here.
+    location ~ \.(br|gz)$ {
+      internal;
+    }
+
+    # The markdown rendition Hugo writes alongside each index.html. `internal`
+    # keeps it reachable only via the negotiation above, so every page has
+    # exactly one public URL. mime.types would serve it as text/plain.
+    location ~ (^|/)llms\.txt$ {
+      internal;
+      types { }
+      default_type text/markdown;
+      charset_types text/markdown;
     }
 
     if ($redirect_uri != "") {
       rewrite ^(.*)$ $redirect_uri redirect;
     }
 
-    index index.html;
+    index $negotiated_index index.html;
     error_page 404 /404.html;
   }
 }

themes/hugo-docs/layouts/_default/baseof.html

@@ -28,14 +28,6 @@
       rel="apple-touch-icon"
       href="{{ "apple-touch-icon.png" | relURL }}"
     />
-    {{ with .OutputFormats.Get "llms" }}
-      <link
-        rel="alternate"
-        type="text/markdown"
-        title="LLM-friendly version"
-        href="{{ .Permalink }}"
-      />
-    {{ end }}
     <title>{{ .Page.Title }} - {{ .Section | default "Documentation" | humanize }}</title>
     {{ block "meta" . }}{{ end }}
     {{ partialCached "html-header-global-meta.html" . }}

themes/hugo-docs/layouts/partials/link.html

@@ -1,8 +1,5 @@
-{{- /* Resolve an internal ref to the correct output format. Accepts a path
-       string (format auto-detected from the calling template) or a dict
-       {path, format} for callers that can't be auto-detected (e.g. nested
-       partials). RelRef preserves an inline #anchor. */ -}}
-{{- $path := . -}}
-{{- $fmt := cond (hasSuffix templates.Current.Parent.Name ".llms.txt") "llms" "html" -}}
-{{- if reflect.IsMap . -}}{{ $path = .path }}{{ with .format }}{{ $fmt = . }}{{ end }}{{- end -}}
-{{- page.RelRef (dict "path" $path "outputFormat" $fmt) -}}
+{{- /* Resolve an internal ref to its canonical URL. Markdown output links to
+       the same URLs the HTML does; nginx serves the markdown rendition there
+       to clients sending `Accept: text/markdown`. RelRef preserves an inline
+       #anchor. */ -}}
+{{- page.RelRef (dict "path" . "outputFormat" "html") -}}

themes/hugo-docs/layouts/partials/prose-md.txt

@@ -28,7 +28,7 @@
   {{- /* ref -> absolute URL */ -}}
   {{- range $m := findRE `\{\{<\s*ref\s+\\?"[^"\\]+\\?"\s*>\}\}` $text -}}
     {{- $p := replaceRE `^\{\{<\s*ref\s+\\?"([^"\\]+)\\?"\s*>\}\}$` "$1" $m -}}
-    {{- $text = replace $text $m (partial "link" (dict "path" $p "format" "llms")) -}}
+    {{- $text = replace $text $m (partial "link" $p) -}}
   {{- end -}}
   {{- /* added/deprecated/removed-in -> release link */ -}}
   {{- range $m := findRE `\{\{<\s*(?:added|deprecated|removed)-in\s+\\?"[^"\\]+\\?"[^}]*>\}\}` $text -}}

themes/hugo-docs/layouts/shortcodes/illu-teaser.llms.txt

@@ -1,3 +1 @@
-{{- $link := .Get "link" -}}
-{{- if hasSuffix $link "/" }}{{ $link = print $link "llms.txt" }}{{ end -}}
-- **[{{ .Get "flag" }}]({{ $link }})** — {{ .Get "title" }}
+- **[{{ .Get "flag" }}]({{ .Get "link" }})** — {{ .Get "title" }}