Merge pull request #24901 from dvdksn/fix/home-markdown-output

fix/home markdown output

Author: dvdksn

content/_index.md

@@ -5,3 +5,30 @@ keywords: Docker, documentation, manual, guide, reference, api, samples
 aliases:
   - /search/
 ---
+
+Docker Documentation helps you learn Docker, install Docker products, and find
+reference material for everyday development and operations tasks.
+
+## Browse docs by area
+
+- [Get started](/get-started/): Learn Docker basics and core concepts.
+- [Guides](/guides/): Follow task-focused walkthroughs for common workflows.
+- [Manuals](/manuals/): Install, configure, and use Docker products.
+- [Reference](/reference/): Browse CLI, API, and file format documentation.
+
+## Featured topics
+
+- [Docker Hardened Images](/dhi/)
+- [Get started with Docker Sandboxes](/ai/sandboxes/get-started/)
+- [Docker Desktop overview](/desktop/)
+- [Install Docker Engine](/engine/install/)
+- [Dockerfile reference](/reference/dockerfile/)
+- [Docker Build overview](/build/)
+
+## Common questions
+
+- [How do I get started with Docker?](/get-started/docker-overview/)
+- [Can I run my AI agent in a sandbox?](/ai/sandboxes/get-started/)
+- [What is a container?](/get-started/docker-concepts/the-basics/what-is-a-container/)
+- [What are Docker Hardened Images?](/dhi/)
+- [Why should I use Docker Compose?](/compose/)

hack/releaser/cloudfront-lambda-redirects.js

@@ -69,10 +69,9 @@ exports.handler = (event, context, callback) => {
     if (!hasFileExtension) {
         if (wantsMarkdown) {
             // Markdown files are flattened: /path/to/page.md not /path/to/page/index.md.
-            // Homepage has no flattened equivalent, so serve llms.txt as the
-            // agent-oriented markdown index of the site.
+            // The homepage markdown output remains at /index.md.
             const stripped = uri.replace(/\/$/, '');
-            uri = stripped === '' ? '/llms.txt' : stripped + '.md';
+            uri = stripped === '' ? '/index.md' : stripped + '.md';
         } else {
             // HTML uses directory structure with index.html
             if (!uri.endsWith("/")) {
@@ -83,8 +82,8 @@ exports.handler = (event, context, callback) => {
         request.uri = uri;
     } else if (wantsMarkdown && uri.endsWith('/index.html')) {
         // If requesting index.html but wants markdown, use the flattened .md file.
-        // Root index.html has no flattened equivalent, so serve llms.txt instead.
-        uri = uri === '/index.html' ? '/llms.txt' : uri.replace(/\/index\.html$/, '.md');
+        // The homepage markdown output lives at /index.md.
+        uri = uri === '/index.html' ? '/index.md' : uri.replace(/\/index\.html$/, '.md');
         request.uri = uri;
     }
 

hugo.yaml

@@ -114,6 +114,7 @@ outputFormats:
 outputs:
   home:
     - html
+    - markdown
     - redirects
     - metadata
     - robots

layouts/_partials/utils/markdown-url.html

@@ -1,2 +1,6 @@
-{{- $path := strings.TrimSuffix "/" .RelPermalink -}}
-{{- printf "%s.md" $path | absURL -}}
+{{- if .IsHome -}}
+  {{- absURL "/index.md" -}}
+{{- else -}}
+  {{- $path := strings.TrimSuffix "/" .RelPermalink -}}
+  {{- printf "%s.md" $path | absURL -}}
+{{- end -}}

layouts/home.llms.txt

@@ -1,22 +1,81 @@
-{{- $pages := where site.RegularPages "Params.sitemap" "!=" false -}}
-{{- $sorted := sort $pages "RelPermalink" -}}
-{{- $grouped := $sorted.GroupBy "Section" -}}
+{{- $home := site.Home -}}
+{{- $manuals := site.GetPage "/manuals" -}}
+{{- $getStarted := site.GetPage "/get-started" -}}
+{{- $reference := site.GetPage "/reference" -}}
 
 # Docker Documentation
 
+{{ with $home.Description -}}
+{{ chomp (replace . "\n" " ") }}
+{{- else -}}
+Docker Documentation is the official documentation site for Docker products,
+including Docker Desktop, Docker Engine, Docker Build, Docker Compose, Docker
+Hub, Docker Scout, and Docker AI features.
+{{- end }}
+
+Use this file as a generated discovery guide for the docs site. For the complete
+page index, use [llms-full.txt](https://docs.docker.com/llms-full.txt).
+
 > 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 }}
-{{- range .Pages }}
-{{- template "pageItem" . }}
+## Primary sections
+
+{{- range sort (where site.Sections "Title" "!=" "") "Weight" }}
+{{- if not (in (slice "includes" "tags") .Section) }}
+- [{{ .LinkTitle | default .Title }}]({{ .Permalink }}): {{ with .Description }}{{ chomp (replace . "\n" " ") }}{{ else }}{{ .Title }} documentation.{{ end }}
+  Markdown: {{ partial "utils/markdown-url.html" . }}
+{{- end }}
+{{- end }}
+
+{{ with $getStarted }}
+## Starter paths
+
+{{- range index .Params "get-started" }}
+- [{{ .title }}]({{ .link | absURL }}): {{ .description }}
+{{- end }}
+{{- range index .Params "get-started2" }}
+- [{{ .title }}]({{ .link | absURL }}): {{ .description }}
+{{- end }}
+{{- end }}
+
+{{ with $manuals }}
+## Product documentation
+
+{{- range .Params.sidebar.groups }}
+{{- $group := . }}
+{{- $items := index $manuals.Params ($group | anchorize) }}
+{{- with $items }}
+
+### {{ $group }}
+{{- range . }}
+- [{{ .title }}]({{ .link | absURL }}): {{ .description }}
+{{- end }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{ with $reference }}
+## Reference entry points
+
+### File formats
+{{- range .Params.grid_files }}
+- [{{ .title }}]({{ .link | absURL }}): {{ .description }}
+{{- end }}
+
+### Command-line interfaces
+{{- range .Params.grid_clis }}
+- [{{ .title }}]({{ .link | absURL }}): {{ .description }}
 {{- end }}
-{{- end -}}
 
-{{- define "pageItem" }}
-{{- if and .Title .Permalink }}
-- [{{ .Title }}]({{ .Permalink }})
-  {{- with .Description }}: {{ chomp (replace . "\n" " ") }}{{- end }}
+### APIs
+{{- range .Params.grid_apis }}
+- [{{ .title }}]({{ .link | absURL }}): {{ .description }}
 {{- end }}
 {{- end }}
+
+## Retrieval guidance
+
+- Prefer section landing pages above for navigation and scope selection.
+- Use [llms-full.txt](https://docs.docker.com/llms-full.txt) when you need the complete documentation corpus.
+- Use page-level markdown routes such as `https://docs.docker.com/engine/install.md` for clean per-page retrieval.

layouts/home.markdown.md

@@ -0,0 +1,3 @@
+# Docker Documentation
+
+{{ .RenderShortcodes }}