chore: implement agent-readiness improvements from audit

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>

hugo.yaml

@@ -102,6 +102,12 @@ outputFormats:
     mediaType: "text/plain"
     notAlternative: true
     permalinkable: false
+  llmsfull:
+    baseName: llms-full
+    isPlainText: true
+    mediaType: "text/plain"
+    notAlternative: true
+    permalinkable: false
 
 # Enable custom output formats
 # (only generate the custom output files once)
@@ -112,6 +118,7 @@ outputs:
     - metadata
     - robots
     - llms
+    - llmsfull
   page:
     - html
     - markdown

layouts/_partials/footer.html

@@ -49,6 +49,11 @@
       class="inline-flex truncate whitespace-normal"
       >llms.txt</a
     >
+    <a
+      href="{{ "llms-full.txt" | relURL }}"
+      class="inline-flex truncate whitespace-normal"
+      >llms-full.txt</a
+    >
   </div>
   <div class="flex items-center justify-end">
     <button
@@ -85,7 +90,6 @@
   class="border-t border-gray-200 bg-gray-100 px-4 py-4 text-sm text-gray-400 md:border-none dark:border-gray-700 dark:bg-gray-900 dark:text-gray-600"
 >
   <span
-    >Copyright © 2013-{{ time.Now.Year }} Docker Inc. All rights
-    reserved.</span
+    >Copyright © 2013-{{ time.Now.Year }} Docker Inc. All rights reserved.</span
   >
 </div>

layouts/_partials/head.html

@@ -2,10 +2,22 @@
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 {{ partial "meta.html" . }}
 {{- range .AlternativeOutputFormats -}}
-  <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink }}" />
+  {{- if eq .Name "markdown" -}}
+    <link
+      rel="{{ .Rel }}"
+      type="{{ .MediaType.Type }}"
+      href="{{ partial "utils/markdown-url.html" $ }}"
+    />
+  {{- else -}}
+    <link
+      rel="{{ .Rel }}"
+      type="{{ .MediaType.Type }}"
+      href="{{ .Permalink }}"
+    />
+  {{- end -}}
 {{ end -}}
 {{ partialCached "utils/css.html" "-" "-" }}
-<link href="/pagefind/pagefind-component-ui.css" rel="stylesheet">
+<link href="/pagefind/pagefind-component-ui.css" rel="stylesheet" />
 {{- if hugo.IsProduction -}}
   <script
     src="https://cdn.cookielaw.org/scripttemplates/otSDKStub.js"

layouts/_partials/meta.html

@@ -3,7 +3,7 @@
   <title>{{ site.Title }}</title>
 {{ else }}
   <title>
-    {{ printf "%s | %s" .LinkTitle site.Title }}
+    {{ printf "%s | %s" .Title site.Title }}
   </title>
 {{ end }}
 {{ if or (eq .Params.sitemap false) (not hugo.IsProduction) }}
@@ -20,11 +20,11 @@
 <link rel="icon" href="/assets/images/favicon-32x32.png" sizes="32x32" />
 <link rel="icon" href="/assets/images/favicon-192x192.png" sizes="192x192" />
 <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
-<link rel="shortcut icon" href="/favicon.ico">
+<link rel="shortcut icon" href="/favicon.ico" />
 <meta name="theme-color" content="#2496ed" />
 
 <!-- SEO -->
-<meta name="twitter:title" itemprop="title name" content="{{ .LinkTitle }}" />
+<meta name="twitter:title" itemprop="title name" content="{{ .Title }}" />
 <meta
   name="twitter:description"
   property="og:description"
@@ -40,7 +40,7 @@
   content="{{ (resources.Get "images/thumbnail.webp").Permalink }}"
 />
 <meta name="twitter:image:alt" content="Docker Documentation" />
-<meta property="og:title" content="{{ .LinkTitle }}" />
+<meta property="og:title" content="{{ .Title }}" />
 <meta property="og:description" content="{{ $description }}" />
 <meta property="og:type" content="website" />
 <meta

layouts/_partials/schema.html

@@ -5,7 +5,7 @@
 {{- $schema := dict
   "@context" "https://schema.org"
   "@type" "TechArticle"
-  "headline" (truncate 110 .LinkTitle)
+  "headline" (truncate 110 .Title)
   "description" $description
   "url" .Permalink
 -}}
@@ -22,7 +22,8 @@
 {{- $schema = merge $schema (dict
   "mainEntityOfPage" (dict "@type" "WebPage" "@id" .Permalink)
   "inLanguage" site.Language.Lang
-) -}}
+  )
+-}}
 
 {{- /* Add author and publisher */ -}}
 {{- $logoUrl := printf "%sassets/images/docker-logo.png" (strings.TrimSuffix "/" site.BaseURL | printf "%s/") -}}
@@ -84,7 +85,6 @@
 
 {{- /* Output the schema as JSON-LD */ -}}
 <script type="application/ld+json">{{ $schema | jsonify | safeJS }}</script>
-
 {{- /* Add BreadcrumbList schema */ -}}
 {{- $breadcrumbs := slice -}}
 {{- $position := 1 -}}
@@ -94,8 +94,8 @@
       "@type" "ListItem"
       "position" $position
       "item" (dict
-        "@id" .Permalink
-        "name" (truncate 110 .LinkTitle)
+      "@id" .Permalink
+      "name" (truncate 110 .LinkTitle)
       )
     -}}
     {{- $breadcrumbs = $breadcrumbs | append $item -}}
@@ -108,8 +108,8 @@
   "@type" "ListItem"
   "position" $position
   "item" (dict
-    "@id" .Permalink
-    "name" (truncate 110 .LinkTitle)
+  "@id" .Permalink
+  "name" (truncate 110 .Title)
   )
 -}}
 {{- $breadcrumbs = $breadcrumbs | append $currentItem -}}

layouts/_partials/utils/markdown-url.html

@@ -0,0 +1,2 @@
+{{- $path := strings.TrimSuffix "/" .RelPermalink -}}
+{{- printf "%s.md" $path | absURL -}}

layouts/api.html

@@ -1,76 +1,174 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  {{ $specURL := urls.Parse (printf "/%s%s.yaml" .File.Dir .File.ContentBaseName) }}
-  <title>{{ .Title }}</title>
-  <!-- needed for adaptive design -->
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <meta name="description" content="{{ .Description }}" />
-  <meta charset="utf-8" />
-  <!-- favicon -->
-  <link rel="icon" href="/assets/images/favicon-32x32.png" sizes="32x32" />
-  <link rel="icon" href="/assets/images/favicon-192x192.png" sizes="192x192" />
-  <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
-  <link rel="shortcut icon" href="/favicon.ico">
-  <!--
+  <head>
+    {{ $specURL := urls.Parse (printf "/%s%s.yaml" .File.Dir .File.ContentBaseName) }}
+    <title>{{ printf "%s | %s" .Title site.Title }}</title>
+    <!-- needed for adaptive design -->
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="{{ .Description }}" />
+    <meta charset="utf-8" />
+    <link rel="canonical" href="{{ .Permalink }}" />
+    <link
+      rel="alternate"
+      href="{{ partial "utils/markdown-url.html" . }}"
+      type="text/markdown"
+      title="{{ .Title }} (Markdown)"
+    />
+    <!-- favicon -->
+    <link rel="icon" href="/assets/images/favicon-32x32.png" sizes="32x32" />
+    <link
+      rel="icon"
+      href="/assets/images/favicon-192x192.png"
+      sizes="192x192"
+    />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+    <link rel="shortcut icon" href="/favicon.ico" />
+    <!--
   Provide a link to the swagger / OpenAPI spec itself. We're currently using
   Swagger (OpenAPI v2) for some, so use a more generic "application/yaml" type.
 
   Once all our specs are updated to OpenAPI v3, we can change this to "application/vnd.oai.openapi"
   -->
-  <link rel="alternate" href="{{ $specURL.String | absURL }}" type="application/yaml" title="{{ .Title }} (Swagger/OpenAPI)" />
-  <style>
-    body {
-      margin: 0;
-      padding: 0;
-    }
+    <link
+      rel="alternate"
+      href="{{ $specURL.String | absURL }}"
+      type="application/yaml"
+      title="{{ .Title }} (Swagger/OpenAPI)"
+    />
+    {{ partial "schema.html" . }}
+    <style>
+      body {
+        margin: 0;
+        color: #1f2933;
+        font-family:
+          Roboto Flex,
+          Roboto,
+          sans-serif;
+        line-height: 1.5;
+      }
 
-    .menu-content>div:first-child {
-      background-color: #086dd7;
-      padding: 16px;
-    }
+      .menu-content > div:first-child {
+        background-color: #086dd7;
+        padding: 16px;
+      }
 
-    .auth-tag,.pat,.oat {
-      border-radius: 4px;
-      color: #fff;
-      padding: 5px;
-    }
+      .auth-tag,
+      .pat,
+      .oat {
+        border-radius: 4px;
+        color: #fff;
+        padding: 5px;
+      }
 
-    .pat {
-      background-color: rgb(149, 80, 124);
-    }
+      .pat {
+        background-color: rgb(149, 80, 124);
+      }
 
-    .pat::after {
-      content: "personal access token";
-    }
+      .pat::after {
+        content: "personal access token";
+      }
 
-    .oat::after {
-      content: "org access token";
-    }
+      .oat::after {
+        content: "org access token";
+      }
 
-    .oat {
-      background-color: rgb(24, 111, 175);
-    }
+      .oat {
+        background-color: rgb(24, 111, 175);
+      }
 
-    .auth-tag:not(:last-child) {
-      margin-right: 5px;
-    }
-  </style>
-</head>
+      .auth-tag:not(:last-child) {
+        margin-right: 5px;
+      }
 
-<body>
-  <noscript>
-    <p>
-      This page is rendered with JavaScript.<br>
-      <a target="_blank" href="{{ $specURL.String | absURL }}" rel="noreferrer">Download {{ .Title }} Swagger/OpenAPI specification</a>
-    </p>
-  </noscript>
-  {{ if or (strings.HasPrefix .RelPermalink "/reference/api/hub/") (strings.HasPrefix .RelPermalink "/reference/api/registry/") }}
-    <redoc spec-url="{{ $specURL.String }}" suppress-warnings="true" lazy-rendering></redoc>
-  {{ else }}
-    <redoc spec-url="{{ $specURL.String }}" hide-hostname="true" suppress-warnings="true" lazy-rendering></redoc>
-  {{ end }}
-  <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
-</body>
+      .api-shell {
+        border-bottom: 1px solid #d9e2ec;
+        padding: 32px 24px;
+      }
 
+      .api-shell article {
+        margin: 0 auto;
+        max-width: 960px;
+      }
+
+      .api-shell h1 {
+        font-size: 2rem;
+        line-height: 1.2;
+        margin: 0 0 12px;
+      }
+
+      .api-shell p {
+        margin: 0 0 16px;
+        max-width: 72ch;
+      }
+
+      .api-links {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 12px;
+        list-style: none;
+        margin: 0;
+        padding: 0;
+      }
+
+      .api-links a {
+        color: #086dd7;
+        text-decoration: none;
+      }
+
+      .api-links a:hover {
+        text-decoration: underline;
+      }
+
+      .redoc-container {
+        min-height: calc(100vh - 220px);
+      }
+    </style>
+  </head>
+
+  <body>
+    <main>
+      <section class="api-shell">
+        <article>
+          <h1>{{ .Title }}</h1>
+          <p>{{ .Description }}</p>
+          <ul class="api-links">
+            <li>
+              <a href="{{ partial "utils/markdown-url.html" . }}"
+                >Open Markdown</a
+              >
+            </li>
+            <li>
+              <a href="{{ $specURL.String | absURL }}"
+                >Download OpenAPI specification</a
+              >
+            </li>
+          </ul>
+          <noscript>
+            <p>
+              This reference uses JavaScript for the interactive explorer. Use
+              the Markdown page or download the OpenAPI specification if
+              JavaScript is unavailable.
+            </p>
+          </noscript>
+        </article>
+      </section>
+      <article class="redoc-container">
+        {{ if or (strings.HasPrefix .RelPermalink "/reference/api/hub/") (strings.HasPrefix .RelPermalink "/reference/api/registry/") }}
+          <redoc
+            spec-url="{{ $specURL.String }}"
+            suppress-warnings="true"
+            lazy-rendering
+          ></redoc>
+        {{ else }}
+          <redoc
+            spec-url="{{ $specURL.String }}"
+            hide-hostname="true"
+            suppress-warnings="true"
+            lazy-rendering
+          ></redoc>
+        {{ end }}
+      </article>
+    </main>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+  </body>
 </html>

layouts/home.llms.txt

@@ -5,6 +5,7 @@
 # Docker Documentation
 
 > MCP endpoint for structured agent access: https://mcp-docs.docker.com/mcp
+> Bulk text corpus for offline indexing: https://docs.docker.com/llms-full.txt
 {{- range $grouped }}
 
 ## {{ humanize .Key }}

layouts/home.llmsfull.txt

@@ -0,0 +1,16 @@
+{{- $pages := where site.RegularPages "Params.sitemap" "!=" false -}}
+{{- $sorted := sort $pages "RelPermalink" -}}
+
+# Docker Documentation full text
+
+> Source index: https://docs.docker.com/llms.txt
+> This file contains page metadata and stable markdown URLs for bulk ingestion.
+{{- range $sorted }}
+
+## {{ .Title }}
+URL: {{ .Permalink }}
+Markdown: {{ partial "utils/markdown-url.html" . }}
+{{- with .Description }}
+Description: {{ chomp (replace . "\n" " ") }}
+{{- end }}
+{{- end }}