From b619ed27d3e4405ae1416ffdb749799087bb39ec Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 13:02:07 +0100
Subject: [PATCH 01/10] hugo: improve shortcode rendering for markdown output

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 hugo.yaml                                     |  4 ++++
 layouts/shortcodes/accordion.markdown.md      |  5 +++++
 layouts/shortcodes/badge.markdown.md          |  1 +
 layouts/shortcodes/button.markdown.md         |  3 +++
 layouts/shortcodes/card.markdown.md           |  1 +
 layouts/shortcodes/cta.markdown.md            |  1 +
 .../shortcodes/desktop-install-v2.markdown.md | 22 +++++++++++++++++++
 layouts/shortcodes/experimental.markdown.md   |  3 +++
 layouts/shortcodes/grid.markdown.md           |  1 +
 layouts/shortcodes/inline-image.markdown.md   |  4 ++++
 layouts/shortcodes/restricted.markdown.md     |  3 +++
 layouts/shortcodes/rss-button.markdown.md     |  1 +
 layouts/shortcodes/summary-bar.markdown.md    |  1 +
 layouts/shortcodes/tabs.markdown.md           |  6 +++++
 layouts/shortcodes/youtube-embed.markdown.md  |  1 +
 15 files changed, 57 insertions(+)
 create mode 100644 layouts/shortcodes/accordion.markdown.md
 create mode 100644 layouts/shortcodes/badge.markdown.md
 create mode 100644 layouts/shortcodes/button.markdown.md
 create mode 100644 layouts/shortcodes/card.markdown.md
 create mode 100644 layouts/shortcodes/cta.markdown.md
 create mode 100644 layouts/shortcodes/desktop-install-v2.markdown.md
 create mode 100644 layouts/shortcodes/experimental.markdown.md
 create mode 100644 layouts/shortcodes/grid.markdown.md
 create mode 100644 layouts/shortcodes/inline-image.markdown.md
 create mode 100644 layouts/shortcodes/restricted.markdown.md
 create mode 100644 layouts/shortcodes/rss-button.markdown.md
 create mode 100644 layouts/shortcodes/summary-bar.markdown.md
 create mode 100644 layouts/shortcodes/tabs.markdown.md
 create mode 100644 layouts/shortcodes/youtube-embed.markdown.md

diff --git a/hugo.yaml b/hugo.yaml
index 369dc8d8c411..19dbcca1edf9 100644
--- a/hugo.yaml
+++ b/hugo.yaml
@@ -92,6 +92,10 @@ outputs:
   section:
     - html
     - markdown
+  taxonomy:
+    - html
+  term:
+    - html
 
 languages:
   en:
diff --git a/layouts/shortcodes/accordion.markdown.md b/layouts/shortcodes/accordion.markdown.md
new file mode 100644
index 000000000000..323631d5bb76
--- /dev/null
+++ b/layouts/shortcodes/accordion.markdown.md
@@ -0,0 +1,5 @@
+{{ $title := .Get "title" -}}
+{{ $body := .InnerDeindent -}}
+**{{ $title }}**
+
+{{ $body }}
diff --git a/layouts/shortcodes/badge.markdown.md b/layouts/shortcodes/badge.markdown.md
new file mode 100644
index 000000000000..9bcae182a4a1
--- /dev/null
+++ b/layouts/shortcodes/badge.markdown.md
@@ -0,0 +1 @@
+{{ $text := .Get "text" }}\[{{ $text }}\]
diff --git a/layouts/shortcodes/button.markdown.md b/layouts/shortcodes/button.markdown.md
new file mode 100644
index 000000000000..345e6a1908fa
--- /dev/null
+++ b/layouts/shortcodes/button.markdown.md
@@ -0,0 +1,3 @@
+{{ $text := .Get "text" -}}
+{{ $url := .Get "url" -}}
+[{{ $text }}]({{ $url }})
diff --git a/layouts/shortcodes/card.markdown.md b/layouts/shortcodes/card.markdown.md
new file mode 100644
index 000000000000..3ee941a0a693
--- /dev/null
+++ b/layouts/shortcodes/card.markdown.md
@@ -0,0 +1 @@
+{{/* Card omitted from markdown output */}}
\ No newline at end of file
diff --git a/layouts/shortcodes/cta.markdown.md b/layouts/shortcodes/cta.markdown.md
new file mode 100644
index 000000000000..c2fc437f3d95
--- /dev/null
+++ b/layouts/shortcodes/cta.markdown.md
@@ -0,0 +1 @@
+{{/* CTA omitted from markdown output */}}
\ No newline at end of file
diff --git a/layouts/shortcodes/desktop-install-v2.markdown.md b/layouts/shortcodes/desktop-install-v2.markdown.md
new file mode 100644
index 000000000000..880e00f6fa61
--- /dev/null
+++ b/layouts/shortcodes/desktop-install-v2.markdown.md
@@ -0,0 +1,22 @@
+{{- $all := .Get "all" -}}
+{{- $win := .Get "win" -}}
+{{- $win_arm_release := .Get "win_arm_release" -}}
+{{- $mac := .Get "mac" -}}
+{{- $linux := .Get "linux" -}}
+{{- $build_path := .Get "build_path" -}}
+Download Docker Desktop:
+{{- if or $all $win }}
+- [Windows](https://desktop.docker.com/win/main/amd64{{ $build_path }}Docker%20Desktop%20Installer.exe)
+{{- end }}
+{{- if $win_arm_release }}
+- [Windows ARM {{ $win_arm_release }}](https://desktop.docker.com/win/main/arm64{{ $build_path }}Docker%20Desktop%20Installer.exe)
+{{- end }}
+{{- if or $all $mac }}
+- [Mac (Apple chip)](https://desktop.docker.com/mac/main/arm64{{ $build_path }}Docker.dmg)
+- [Mac (Intel chip)](https://desktop.docker.com/mac/main/amd64{{ $build_path }}Docker.dmg)
+{{- end }}
+{{- if or $all $linux }}
+- [Linux (Debian)](https://desktop.docker.com/linux/main/amd64{{ $build_path }}docker-desktop-amd64.deb)
+- [Linux (RPM)](https://desktop.docker.com/linux/main/amd64{{ $build_path }}docker-desktop-x86_64.rpm)
+- [Linux (Arch)](https://desktop.docker.com/linux/main/amd64{{ $build_path }}docker-desktop-x86_64.pkg.tar.zst)
+{{- end }}
diff --git a/layouts/shortcodes/experimental.markdown.md b/layouts/shortcodes/experimental.markdown.md
new file mode 100644
index 000000000000..9da71ee33313
--- /dev/null
+++ b/layouts/shortcodes/experimental.markdown.md
@@ -0,0 +1,3 @@
+> **{{ .Get "title" | default (i18n "experimental") }}**
+>
+> {{ .InnerDeindent }}
diff --git a/layouts/shortcodes/grid.markdown.md b/layouts/shortcodes/grid.markdown.md
new file mode 100644
index 000000000000..8c88897104ff
--- /dev/null
+++ b/layouts/shortcodes/grid.markdown.md
@@ -0,0 +1 @@
+{{/* Grid omitted from markdown output */}}
\ No newline at end of file
diff --git a/layouts/shortcodes/inline-image.markdown.md b/layouts/shortcodes/inline-image.markdown.md
new file mode 100644
index 000000000000..26b12c9383a7
--- /dev/null
+++ b/layouts/shortcodes/inline-image.markdown.md
@@ -0,0 +1,4 @@
+{{ $src := .Get "src" }}
+{{ $alt := .Get "alt" }}
+{{ $title := .Get "title" }}
+![{{ $alt }}]({{ $src }}{{ with $title }} "{{ . }}"{{ end }})
\ No newline at end of file
diff --git a/layouts/shortcodes/restricted.markdown.md b/layouts/shortcodes/restricted.markdown.md
new file mode 100644
index 000000000000..dd18b991b61f
--- /dev/null
+++ b/layouts/shortcodes/restricted.markdown.md
@@ -0,0 +1,3 @@
+> **{{ .Get "title" | default (i18n "restricted") }}**
+>
+> {{ .InnerDeindent }}
diff --git a/layouts/shortcodes/rss-button.markdown.md b/layouts/shortcodes/rss-button.markdown.md
new file mode 100644
index 000000000000..bf8eebe923ba
--- /dev/null
+++ b/layouts/shortcodes/rss-button.markdown.md
@@ -0,0 +1 @@
+{{/* RSS button omitted from markdown output */}}
\ No newline at end of file
diff --git a/layouts/shortcodes/summary-bar.markdown.md b/layouts/shortcodes/summary-bar.markdown.md
new file mode 100644
index 000000000000..1434bcbee649
--- /dev/null
+++ b/layouts/shortcodes/summary-bar.markdown.md
@@ -0,0 +1 @@
+{{/* Summary bar omitted from markdown output */}}
\ No newline at end of file
diff --git a/layouts/shortcodes/tabs.markdown.md b/layouts/shortcodes/tabs.markdown.md
new file mode 100644
index 000000000000..dc4f50c50fc7
--- /dev/null
+++ b/layouts/shortcodes/tabs.markdown.md
@@ -0,0 +1,6 @@
+{{ with .Inner }}{{/* don't do anything, just call it */}}{{ end -}}
+{{ range (.Store.Get "tabs") -}}
+**{{ .name }}**
+
+{{ .content }}
+{{- end -}}
diff --git a/layouts/shortcodes/youtube-embed.markdown.md b/layouts/shortcodes/youtube-embed.markdown.md
new file mode 100644
index 000000000000..3dde39c8c007
--- /dev/null
+++ b/layouts/shortcodes/youtube-embed.markdown.md
@@ -0,0 +1 @@
+{{/* YouTube embed omitted from markdown output */}}
\ No newline at end of file

From 58ca053f9826ab68c4fc39a723b2799abdb8b11d Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 13:42:20 +0100
Subject: [PATCH 02/10] hugo: add post-process script to flatten markdown files

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 Dockerfile               |  1 +
 hack/flatten-markdown.sh | 22 ++++++++++++++++++++++
 2 files changed, 23 insertions(+)
 create mode 100755 hack/flatten-markdown.sh

diff --git a/Dockerfile b/Dockerfile
index aa4957bce567..2ec633711fc3 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -51,6 +51,7 @@ ARG DOCS_URL="https://docs.docker.com"
 ENV HUGO_CACHEDIR="/tmp/hugo_cache"
 RUN --mount=type=cache,target=/tmp/hugo_cache \
     hugo --gc --minify -e $HUGO_ENV -b $DOCS_URL
+RUN ./hack/flatten-markdown.sh public
 
 # lint lints markdown files
 FROM ghcr.io/igorshubovych/markdownlint-cli:v0.45.0 AS lint
diff --git a/hack/flatten-markdown.sh b/hack/flatten-markdown.sh
new file mode 100755
index 000000000000..d055dc9bdb34
--- /dev/null
+++ b/hack/flatten-markdown.sh
@@ -0,0 +1,22 @@
+#!/bin/sh
+set -e
+
+# Flatten markdown files from public/path/to/page/index.md to public/path/to/page.md
+# This makes markdown output links work correctly
+
+PUBLIC_DIR="${1:-public}"
+
+[ -d "$PUBLIC_DIR" ] || { echo "Error: Directory $PUBLIC_DIR does not exist"; exit 1; }
+
+find "$PUBLIC_DIR" -type f -name 'index.md' | while read -r file; do
+  # Skip the root index.md
+  [ "$file" = "$PUBLIC_DIR/index.md" ] && continue
+
+  # Get the directory containing index.md
+  dir="${file%/*}"
+
+  # Move index.md to parent directory with directory name
+  mv "$file" "${dir%/*}/${dir##*/}.md"
+done
+
+echo "Flattened markdown files in $PUBLIC_DIR"

From b3a1fe27ba2b5bbd8659a9025f20df8aff82582b Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 13:42:38 +0100
Subject: [PATCH 03/10] site: add rel link to markdown output

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/partials/head.html | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/layouts/partials/head.html b/layouts/partials/head.html
index 4c1455512c37..18bdb010b718 100644
--- a/layouts/partials/head.html
+++ b/layouts/partials/head.html
@@ -1,6 +1,9 @@
 <meta charset="utf-8" />
 <meta name="viewport" content="width=device-width, initial-scale=1" />
 {{ partial "meta.html" . }}
+{{- range .AlternativeOutputFormats -}}
+  <link rel="{{ .Rel }}" type="{{ .MediaType.Type }}" href="{{ .Permalink }}" />
+{{ end -}}
 {{ partial "utils/css.html" "-" }}
 {{- if hugo.IsProduction -}}
   <script

From b45c1b846e715ecfe64a075cd1e13985bc8b00b9 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 14:00:07 +0100
Subject: [PATCH 04/10] site: update page opts menu ref to markdown pages

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/partials/md-dropdown.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/layouts/partials/md-dropdown.html b/layouts/partials/md-dropdown.html
index 77afc3a7dfbf..fa18ca9bf132 100644
--- a/layouts/partials/md-dropdown.html
+++ b/layouts/partials/md-dropdown.html
@@ -78,7 +78,7 @@
 <script>
     function getCurrentPlaintextUrl() {
       const url = window.location.href.split("#")[0].replace(/\/$/, "");
-      return `${url}/index.md`;
+      return `${url}.md`;
     }
 
     function copyMarkdown() {

From 8e88adb4ad1bac2ee4be911d9d417cf28267b2dd Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 14:36:04 +0100
Subject: [PATCH 05/10] site: improve the page options menu

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/partials/md-dropdown.html | 136 +++++++++++++++---------------
 1 file changed, 66 insertions(+), 70 deletions(-)

diff --git a/layouts/partials/md-dropdown.html b/layouts/partials/md-dropdown.html
index fa18ca9bf132..833bd627ca6d 100644
--- a/layouts/partials/md-dropdown.html
+++ b/layouts/partials/md-dropdown.html
@@ -1,79 +1,75 @@
-<details id="markdownDropdown" class="ml-3 group relative z-10 inline-block" data-heap-id="markdown-dropdown">
-    <summary
-      class="dropdown-base hover:bg-gray-50 dark:hover:bg-gray-900 inline-flex cursor-pointer items-center gap-0 py-1 pl-2 text-sm font-semibold transition-colors"
-      data-heap-id="markdown-dropdown-toggle"
+<div class="ml-3 relative inline-block" x-data="{ open: false }" @click.outside="open = false">
+  <div class="flex shadow rounded-sm overflow-hidden border border-gray-200 dark:border-gray-700">
+    <!-- Primary copy button -->
+    <button
+      onclick="copyMarkdown()"
+      data-heap-id="copy-markdown-button"
+      class="bg-white dark:bg-gray-800 hover:bg-gray-50 dark:hover:bg-gray-700 flex cursor-pointer items-center gap-2 px-3 py-2 text-sm transition-colors whitespace-nowrap text-gray-900 dark:text-white"
     >
-      <span class="font-normal">Page options</span>
-      <span class="icon-svg transition-transform group-open:rotate-180">
-        {{ partialCached "icon" "arrow_drop_down" "arrow_drop_down" }}
+      <span class="icon-svg icon-sm">
+        {{ partial "icon" "content_copy" }}
       </span>
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
-      </svg>
-    </summary>
+      <span class="icon-svg icon-sm hidden">
+        {{ partial "icon" "check_circle" }}
+      </span>
+      <span>Copy as Markdown</span>
+    </button>
 
-    <!-- Dropdown menu -->
-    <div
-      class="dropdown-base absolute right-0 z-50 mt-1 w-65 origin-top-right p-2 text-sm shadow-md [display:none] group-open:[display:block]"
-      data-heap-id="markdown-dropdown-menu"
+    <!-- Dropdown toggle -->
+    <button
+      @click="open = !open"
+      type="button"
+      data-heap-id="markdown-dropdown-toggle"
+      class="bg-white dark:bg-gray-800 hover:bg-gray-50 dark:hover:bg-gray-700 flex items-center justify-center px-2 border-l border-gray-200 dark:border-gray-700 transition-colors text-gray-900 dark:text-white"
+      aria-label="More options"
     >
-      <button
-        onclick="copyMarkdown()"
-        data-heap-id="copy-markdown-button"
-        class="sub-button"
-      >
-        <span class="icon-svg mt-[2px] text-base leading-none">
-          {{ partial "icon" "content_copy" }}
-        </span>
-        <span class="icon-svg hidden mt-[2px] text-base leading-none">
-          {{ partial "icon" "check_circle" }}
-        </span>
-        <div class="leading-tight">
-          <div class="text-base">Copy page as Markdown for LLMs</div>
-        </div>
-      </button>
-
-      <button
-        onclick="viewPlainText()"
-        data-heap-id="view-markdown-button"
-        class="sub-button"
-      >
-        <span class="icon-svg mt-[2px] text-base leading-none">
-          {{ partial "icon" "description" }}
-        </span>
-        <div class="leading-tight">
-          <div class="text-base">View page as plain text</div>
-        </div>
-      </button>
+      <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7"></path>
+      </svg>
+    </button>
+  </div>
 
-      <button
-        onclick="openInDocsAI()"
-        data-heap-id="search-docs-ai-button"
-        class="sub-button"
-      >
-        <span class="icon-svg mt-[2px] text-base leading-none">
-          {{ partial "icon" "search" }}
-        </span>
-        <div class="leading-tight">
-          <div class="text-base">Ask questions with Docs AI</div>
-        </div>
-      </button>
-      {{ if eq hugo.Environment "production" }}
-       <button
-        onclick="openInClaude()"
-        data-heap-id="search-docs-ai-button"
-        class="sub-button"
-      >
-        <span class="icon-svg mt-[2px] text-base leading-none">
-          {{ partial "icon" "/icons/claude.svg" }}
-        </span>
-        <div class="leading-tight">
-          <div class="text-base">Open in Claude</div>
-        </div>
-      </button>
-      {{ end }}
+  <!-- Dropdown menu -->
+  <div
+    x-show="open"
+    x-collapse
+    x-cloak
+    class="absolute right-0 top-full mt-1 min-w-full bg-white dark:bg-gray-800 rounded-sm shadow-lg overflow-hidden z-50 border border-gray-200 dark:border-gray-700"
+    data-heap-id="markdown-dropdown-menu"
+  >
+    <button
+      onclick="viewPlainText()"
+      data-heap-id="view-markdown-button"
+      class="flex w-full items-center gap-2 px-4 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 whitespace-nowrap"
+    >
+      <span class="icon-svg icon-sm">
+        {{ partialCached "icon" "open_in_new" "open_in_new" }}
+      </span>
+      <span>Open Markdown</span>
+    </button>
 
-    </div>
-  </details>
+    <button
+      onclick="openInDocsAI()"
+      data-heap-id="search-docs-ai-button"
+      class="flex w-full items-center gap-2 px-4 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 whitespace-nowrap"
+    >
+      <span class="icon-svg icon-sm">
+        {{ partialCached "icon" "search" "search" }}
+      </span>
+      <span>Ask Docs AI</span>
+    </button>
+    <button
+      onclick="openInClaude()"
+      data-heap-id="open-claude-button"
+      class="flex w-full items-center gap-2 px-4 py-2 text-sm text-gray-700 dark:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-700 whitespace-nowrap"
+    >
+      <span class="icon-svg icon-sm">
+        {{ partialCached "icon" "/icons/claude.svg" "claude" }}
+      </span>
+      <span>Open in Claude</span>
+    </button>
+  </div>
+</div>
 
 <script>
     function getCurrentPlaintextUrl() {

From 390938c17cf60f41807a53d25ea6fbd8ee2ebb90 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 14:39:13 +0100
Subject: [PATCH 06/10] site: support content negotiation for
 markdown/plaintext

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 hack/releaser/cloudfront-lambda-redirects.js | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/hack/releaser/cloudfront-lambda-redirects.js b/hack/releaser/cloudfront-lambda-redirects.js
index a214d7ee560c..186824aa6474 100644
--- a/hack/releaser/cloudfront-lambda-redirects.js
+++ b/hack/releaser/cloudfront-lambda-redirects.js
@@ -52,20 +52,31 @@ exports.handler = (event, context, callback) => {
         return
     }
 
-    // Handle directory requests by appending index.html for requests without file extensions
+    // Check Accept header for markdown/text requests
+    const headers = request.headers;
+    const acceptHeader = headers.accept ? headers.accept[0].value : '';
+    const wantsMarkdown = acceptHeader.includes('text/markdown') ||
+                          acceptHeader.includes('text/plain');
+
+    // Handle directory requests by appending index.html or index.md for requests without file extensions
     let uri = request.uri;
 
     // Check if the URI has a dot after the last slash (indicating a filename)
     // This is more accurate than just checking the end of the URI
     const hasFileExtension = /\.[^/]*$/.test(uri.split('/').pop());
 
-    // If it's not a file, treat it as a directory and append index.html
+    // If it's not a file, treat it as a directory
     if (!hasFileExtension) {
-        // Ensure the URI ends with a slash before appending index.html
+        // Ensure the URI ends with a slash before appending index file
         if (!uri.endsWith("/")) {
             uri += "/";
         }
-        uri += "index.html";
+        // Serve markdown if Accept header requests it, otherwise serve HTML
+        uri += wantsMarkdown ? "index.md" : "index.html";
+        request.uri = uri;
+    } else if (wantsMarkdown && uri.endsWith('.html')) {
+        // If requesting a specific HTML file but wants markdown, try the .md version
+        uri = uri.replace(/\.html$/, '.md');
         request.uri = uri;
     }
 

From aa10ed9784f47922c0928fc047a42db9c6d476b1 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 14:59:18 +0100
Subject: [PATCH 07/10] hugo: improve metadata rendering for markdown output

Render title and related pages as front matter

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/_default/list.markdown.md   | 39 ++++++++++++++++++++++++++---
 layouts/_default/single.markdown.md | 35 +++++++++++++++++++++++++-
 2 files changed, 69 insertions(+), 5 deletions(-)

diff --git a/layouts/_default/list.markdown.md b/layouts/_default/list.markdown.md
index 0cbb619e2522..ab2747bc38c9 100644
--- a/layouts/_default/list.markdown.md
+++ b/layouts/_default/list.markdown.md
@@ -1,5 +1,36 @@
-# {{ .Title }}
+---
+title: {{ .Title }}
+url: {{ .Permalink }}
+{{- range .Ancestors }}
+  {{- if and (not .IsHome) .Permalink }}
+parent:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+  {{- break }}
+  {{- end }}
+{{- end }}
+{{- if .Ancestors }}
+breadcrumbs:
+{{- range .Ancestors.Reverse }}
+  {{- if and (not .IsHome) .Permalink }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+  {{- end }}
+{{- end }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+{{- end }}
+{{- $children := where .Pages "Permalink" "ne" "" }}
+{{- if $children }}
+children:
+{{- range $children }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+    {{- with .Description }}
+    description: {{ . }}
+    {{- end }}
+{{- end }}
+{{- end }}
+---
+
 {{ .RenderShortcodes }}
-{{ range where .Pages "Permalink" "ne" "" }}
-- [{{ .Title }}]({{ .Permalink }})
-{{ end }}
diff --git a/layouts/_default/single.markdown.md b/layouts/_default/single.markdown.md
index 2e89e09128f5..40c1778180d4 100644
--- a/layouts/_default/single.markdown.md
+++ b/layouts/_default/single.markdown.md
@@ -1,2 +1,35 @@
-# {{ .Title }}
+---
+title: {{ .Title }}
+url: {{ .Permalink }}
+{{- range .Ancestors }}
+  {{- if and (not .IsHome) .Permalink }}
+parent:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+  {{- break }}
+  {{- end }}
+{{- end }}
+{{- if .Ancestors }}
+breadcrumbs:
+{{- range .Ancestors.Reverse }}
+  {{- if and (not .IsHome) .Permalink }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+  {{- end }}
+{{- end }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+{{- end }}
+{{- with .NextInSection }}
+next:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+{{- end }}
+{{- with .PrevInSection }}
+prev:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+{{- end }}
+---
+
 {{ .RenderShortcodes }}

From 8fb9d3a9a5b07c07478ffa91007ee68deecdcd41 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 15:00:50 +0100
Subject: [PATCH 08/10] ci: flatten markdown files for preview builds

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 netlify.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/netlify.toml b/netlify.toml
index d773ce4389bb..6cee9928c01b 100644
--- a/netlify.toml
+++ b/netlify.toml
@@ -10,4 +10,4 @@ HUGO_ENVIRONMENT = "preview"
 SECRETS_SCAN_OMIT_PATHS = "public/contribute/file-conventions/index.html"
 
 [context.deploy-preview]
-command = "hugo --gc --minify -b $DEPLOY_PRIME_URL && npx pagefind@v1.3.0"
+command = "hugo --gc --minify -b $DEPLOY_PRIME_URL && ./hack/flatten-markdown.sh && npx pagefind@v1.3.0"

From 8c05ef70b81d9440b55d8de249b31cce079abd48 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 15:42:05 +0100
Subject: [PATCH 09/10] hugo: render markdown for api/cli reference pages

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/_default/api.markdown.md | 41 +++++++++++++++
 layouts/_default/cli.markdown.md | 88 ++++++++++++++++++++++++++++++++
 2 files changed, 129 insertions(+)
 create mode 100644 layouts/_default/api.markdown.md
 create mode 100644 layouts/_default/cli.markdown.md

diff --git a/layouts/_default/api.markdown.md b/layouts/_default/api.markdown.md
new file mode 100644
index 000000000000..ff3bef069369
--- /dev/null
+++ b/layouts/_default/api.markdown.md
@@ -0,0 +1,41 @@
+---
+title: {{ .Title }}
+url: {{ .Permalink }}
+{{- range .Ancestors }}
+  {{- if and (not .IsHome) .Permalink }}
+parent:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+  {{- break }}
+  {{- end }}
+{{- end }}
+{{- if .Ancestors }}
+breadcrumbs:
+{{- range .Ancestors.Reverse }}
+  {{- if and (not .IsHome) .Permalink }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+  {{- end }}
+{{- end }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+{{- end }}
+{{- with .NextInSection }}
+next:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+{{- end }}
+{{- with .PrevInSection }}
+prev:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+{{- end }}
+{{- $specURL := urls.Parse (printf "/%s%s.yaml" .File.Dir .File.ContentBaseName) }}
+openapi_spec: {{ $specURL.String | absURL }}
+---
+
+{{ .Content }}
+
+**OpenAPI Specification:** [{{ .Title }} API Spec]({{ $specURL.String | absURL }})
+
+This page provides interactive API documentation. For the machine-readable OpenAPI specification, see the link above.
diff --git a/layouts/_default/cli.markdown.md b/layouts/_default/cli.markdown.md
new file mode 100644
index 000000000000..99cfd9ecc06e
--- /dev/null
+++ b/layouts/_default/cli.markdown.md
@@ -0,0 +1,88 @@
+{{- $data := "" }}
+{{- if .Params.datafolder }}
+  {{- $data = index (index site.Data .Params.datafolder) .Params.datafile }}
+{{- else }}
+  {{- $data = index site.Data .Params.datafile }}
+{{- end -}}
+---
+title: {{ .Title }}
+url: {{ .Permalink }}
+{{- range .Ancestors }}
+  {{- if and (not .IsHome) .Permalink }}
+parent:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+  {{- break }}
+  {{- end }}
+{{- end }}
+{{- if .Ancestors }}
+breadcrumbs:
+{{- range .Ancestors.Reverse }}
+  {{- if and (not .IsHome) .Permalink }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+  {{- end }}
+{{- end }}
+  - title: {{ .Title }}
+    url: {{ .Permalink }}
+{{- end }}
+{{- with .NextInSection }}
+next:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+{{- end }}
+{{- with .PrevInSection }}
+prev:
+  title: {{ .Title }}
+  url: {{ .Permalink }}
+{{- end }}
+---
+
+{{ with $data.short }}**Description:** {{ . }}{{ end }}
+
+{{ with $data.usage }}**Usage:** `{{ . }}`{{ end }}
+
+{{ with $data.aliases }}{{ $aliases := strings.Replace . (printf "%s, " $.Title) "" }}**Aliases:** {{ range $i, $alias := (strings.Split $aliases ", ") }}{{ if $i }}, {{ end }}`{{ $alias }}`{{ end }}{{ end }}
+
+{{ .Content }}
+
+{{ if $data.deprecated }}> [!WARNING]
+> **Deprecated**
+>
+> This command is deprecated. It may be removed in a future Docker version.
+{{ end }}
+
+{{ if or $data.experimental $data.experimentalcli }}> [!NOTE]
+> **Experimental**
+>
+> This command is experimental. Experimental features are intended for testing and feedback as their functionality or design may change between releases without warning or can be removed entirely in a future release.
+{{ end }}
+
+{{ with $data.kubernetes }}**Orchestrator:** Kubernetes{{ end }}
+{{ with $data.swarm }}**Orchestrator:** Swarm{{ end }}
+
+{{ with $data.long }}## Description
+
+{{ . }}
+{{ end }}
+
+{{ with $data.options }}{{ $opts := where . "hidden" false }}{{ with $opts }}## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+{{ range . }}{{ $short := .shorthand }}{{ $long := .option }}| {{ with $short }}`-{{ . }}`, {{ end }}`--{{ $long }}` | {{ with .default_value }}{{ $skipDefault := `[],map[],false,0,0s,default,'',""` }}{{ cond (in $skipDefault .) "" (printf "`%s`" .) }}{{ end }} | {{ with .min_api_version }}API {{ . }}+{{ end }}{{ with .deprecated }} **Deprecated**{{ end }}{{ with .experimental }} **experimental (daemon)**{{ end }}{{ with .experimentalcli }} **experimental (CLI)**{{ end }}{{ with .kubernetes }} **Kubernetes**{{ end }}{{ with .swarm }} **Swarm**{{ end }}{{ if .description }} {{ strings.Replace .description "\n" "<br>" }}{{ end }} |
+{{ end }}
+{{ end }}{{ end }}
+
+{{ with $data.examples }}## Examples
+
+{{ . }}
+{{ end }}
+
+{{ if eq .Kind "section" }}## Subcommands
+
+| Command | Description |
+|---------|-------------|
+{{ range .Pages }}{{ if and .Params.datafolder .Params.datafile }}{{ $subdata := index (index site.Data .Params.datafolder) .Params.datafile }}| [`{{ .Title }}`]({{ .Permalink }}) | {{ $subdata.short }} |
+{{ end }}{{ end }}
+{{ end }}

From 23a6fde9cb43f4ce326d470fcd04e1e56e1a6ec1 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 12 Jan 2026 15:45:33 +0100
Subject: [PATCH 10/10] site: render page info dropdown on cli pages

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 layouts/_default/cli.html | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/layouts/_default/cli.html b/layouts/_default/cli.html
index 7f12bdab1151..97e52e09bff5 100644
--- a/layouts/_default/cli.html
+++ b/layouts/_default/cli.html
@@ -10,7 +10,12 @@
   <div class="flex w-full">
     <article class="prose min-w-0 flex-[2_2_0%] max-w-4xl dark:prose-invert">
     {{ partial "breadcrumbs.html" . }}
-    <h1>{{ .Title }}</h1>
+    <div class="flex items-start justify-between gap-4">
+      <h1>{{ .Title }}</h1>
+      <div class="md-dropdown ml-auto mr-4 hidden lg:block">
+        {{ partial "md-dropdown.html" . }}
+      </div>
+    </div>
     <div class="overflow-x-auto">
       <table>
         <tbody>