From 4f3ea96409898459cad4fea5139948853dd75683 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 4 Nov 2025 08:32:52 +0100
Subject: [PATCH 1/2] test: replace wjdp/htmltest with lychee

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 .gitignore    |  1 +
 .htmltest.yml | 16 ----------------
 Dockerfile    | 23 ++++++++++++++++-------
 lychee.toml   | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 66 insertions(+), 23 deletions(-)
 delete mode 100644 .htmltest.yml
 create mode 100644 lychee.toml

diff --git a/.gitignore b/.gitignore
index fb19501a8140..6f86c2f4f1d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,3 +10,4 @@ public
 resources
 static/pagefind
 tmp
+.lycheecache
diff --git a/.htmltest.yml b/.htmltest.yml
deleted file mode 100644
index 1be65b82355a..000000000000
--- a/.htmltest.yml
+++ /dev/null
@@ -1,16 +0,0 @@
-DirectoryPath: "public"
-EnforceHTTPS: false
-CheckDoctype: false
-CheckExternal: false
-IgnoreAltMissing: true
-IgnoreAltEmpty: true
-IgnoreEmptyHref: true
-IgnoreDirectoryMissingTrailingSlash: true
-IgnoreURLs:
-- "^/reference/api/hub/.*$"
-- "^/reference/api/engine/v.+/#.*$"
-- "^/reference/api/registry/.*$"
-IgnoreDirs:
-- "registry/configuration"
-- "compose/compose-file" # temporarily ignore until upstream is fixed
-CacheExpires: "6h"
diff --git a/Dockerfile b/Dockerfile
index 7fc6c996b5d2..e1c54ea06f28 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -3,7 +3,8 @@
 
 ARG ALPINE_VERSION=3.21
 ARG GO_VERSION=1.24
-ARG HTMLTEST_VERSION=0.17.0
+# LYCHEE_VERSION v0.21.0
+ARG LYCHEE_VERSION=92a3a7c
 ARG VALE_VERSION=3.11.2
 ARG HUGO_VERSION=0.141.0
 ARG NODE_VERSION=22
@@ -61,11 +62,15 @@ RUN --mount=type=bind,target=. \
     --ignore "content/manuals/desktop/previous-versions/*.md"
 
 # test validates HTML output and checks for broken links
-FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS test
+FROM lycheeverse/lychee:sha-${LYCHEE_VERSION}-alpine AS test
 WORKDIR /test
 COPY --from=build /project/public ./public
-ADD .htmltest.yml .htmltest.yml
-RUN htmltest
+ADD lychee.toml lychee.toml
+RUN lychee --config lychee.toml \
+    --base-url file:///test/public \
+    --include-fragments \
+    --verbose \
+    ./public
 
 # vale
 FROM jdkato/vale:v${VALE_VERSION} AS vale-run
@@ -134,11 +139,15 @@ ENV HUGO_MODULE_REPLACEMENTS="github.com/${UPSTREAM_MODULE_NAME} -> github.com/$
 RUN hugo --ignoreVendorPaths "github.com/${UPSTREAM_MODULE_NAME}"
 
 # validate-upstream validates HTML output for upstream builds
-FROM wjdp/htmltest:v${HTMLTEST_VERSION} AS validate-upstream
+FROM lycheeverse/lychee:sha-${LYCHEE_VERSION}-alpine AS validate-upstream
 WORKDIR /test
 COPY --from=build-upstream /project/public ./public
-ADD .htmltest.yml .htmltest.yml
-RUN htmltest
+ADD lychee.toml lychee.toml
+RUN lychee --config lychee.toml \
+    --base-url file:///test/public \
+    --include-fragments \
+    --verbose \
+    ./public
 
 # unused-media checks for unused graphics and other media
 FROM alpine:${ALPINE_VERSION} AS unused-media
diff --git a/lychee.toml b/lychee.toml
new file mode 100644
index 000000000000..3841abe49f40
--- /dev/null
+++ b/lychee.toml
@@ -0,0 +1,49 @@
+# Lychee link checker configuration
+# Replacement for htmltest
+
+# Cache configuration
+cache = true
+max_cache_age = "6h"
+
+require_https = false
+# base_url = "https://docs.docker.com"
+
+# Explicitly include file scheme for local fragment checking
+# This is crucial for checking fragments in local HTML files
+scheme = ["file"]
+
+exclude = [
+  # Exclude external links (we only check internal links)
+  '^https?://.*',
+  # Ignore specific internal paths
+  '/reference/api/hub/',
+  # Exclude API engine version links with fragments (Redoc JavaScript-rendered)
+  '/reference/api/engine/version/v[0-9.]+/#',
+  '/reference/api/registry/',
+]
+
+# Exclude specific directories and file types
+exclude_path = [
+  'registry/configuration',
+  'compose/compose-file',
+  # Exclude markdown/txt files from being scanned
+  '\.md$',
+  '\.txt$',
+]
+
+# Accept these HTTP status codes as valid
+accept = [200, 204, 301, 302, 307, 308, 429]
+
+# Configure retries and timeout
+max_retries = 2
+timeout = 10
+
+# Set user agent
+user_agent = "lychee/link-checker"
+
+# Check fragments (anchors) in URLs
+# This is essential for validating internal anchor links
+include_fragments = true
+
+# Don't ignore localhost since we're checking local files
+exclude_loopback = false

From ab2a97f395405c73b9818868eed009689112f2b3 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Mon, 17 Nov 2025 11:28:02 +0100
Subject: [PATCH 2/2] chore: fix broken internal link to engine api reference

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
---
 content/manuals/engine/swarm/manage-nodes.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/manuals/engine/swarm/manage-nodes.md b/content/manuals/engine/swarm/manage-nodes.md
index bd50e2070838..fc31e006acd1 100644
--- a/content/manuals/engine/swarm/manage-nodes.md
+++ b/content/manuals/engine/swarm/manage-nodes.md
@@ -203,7 +203,7 @@ a `PluginSpec` instead of a `ContainerSpec`.
 
 The [`PluginSpec`](/engine/extend/plugin_api/#json-specification)
 is defined by the plugin developer. To add the plugin to all Docker nodes, use
-the [`service/create`](/reference/api/engine/v1.31/#operation/ServiceCreate) API, passing
+the [`service/create`](/reference/api/engine/version/v1.52/#operation/ServiceCreate) API, passing
 the `PluginSpec` JSON defined in the `TaskTemplate`.
 
 ## Leave the swarm