UI: send docs markdown links to public docs

dahifi · dahifi · commit bfe1eecda11c · 2026-06-02T10:25:35.000-04:00
diff --git a/ui/src/ui/markdown.test.ts b/ui/src/ui/markdown.test.ts
@@ -582,6 +582,45 @@ PY
       expect(html).toBe("<p><a>report.docx</a></p>\n");
     });
 
+    it("rewrites docs-root markdown links to the public docs host", () => {
+      const html = toSanitizedMarkdownHtml(
+        "[Workspace concept](/concepts/agent-workspace#agent-workspace)",
+      );
+      expect(html).toBe(
+        '<p><a href="https://docs.openclaw.ai/concepts/agent-workspace#agent-workspace" rel="noreferrer noopener" target="_blank">Workspace concept</a></p>\n',
+      );
+    });
+
+    it("rewrites nested docs links while preserving Control UI app routes", () => {
+      const html = toSanitizedMarkdownHtml(
+        "[Discord docs](/channels/discord) [usage](/usage) [chat](/chat) [media](/api/chat/media/outgoing/file)",
+      );
+      expect(html).toBe(
+        '<p><a href="https://docs.openclaw.ai/channels/discord" rel="noreferrer noopener" target="_blank">Discord docs</a> <a href="/usage" rel="noreferrer noopener" target="_blank">usage</a> <a href="/chat" rel="noreferrer noopener" target="_blank">chat</a> <a href="/api/chat/media/outgoing/file" rel="noreferrer noopener" target="_blank">media</a></p>\n',
+      );
+    });
+
+    it("rewrites docs links rendered in markdown sidebars", () => {
+      const container = document.createElement("div");
+
+      render(
+        renderMarkdownSidebar({
+          content: {
+            kind: "markdown",
+            content: "Read the [agent workspace](/concepts/agent-workspace) docs.",
+          },
+          error: null,
+          onClose: () => undefined,
+          onViewRawText: () => undefined,
+        }),
+        container,
+      );
+
+      expect(container.querySelector(".sidebar-markdown a")?.getAttribute("href")).toBe(
+        "https://docs.openclaw.ai/concepts/agent-workspace",
+      );
+    });
+
     it("keeps app-relative links navigable", () => {
       const html = toSanitizedMarkdownHtml("[usage](/usage)");
       expect(html).toBe(
diff --git a/ui/src/ui/markdown.ts b/ui/src/ui/markdown.ts
@@ -87,6 +87,64 @@ const INLINE_DATA_IMAGE_RE = /^data:image\/[a-z0-9.+-]+;base64,/i;
 const HOST_LOCAL_FILE_HREF_RE =
   /^(?:~\/|\/(?:Users|home|tmp|private\/tmp|var\/folders|private\/var\/folders)\/|\/[A-Za-z]:\/|[A-Za-z]:[\\/])/;
 const markdownCache = new Map<string, string>();
+const DOCS_BASE_URL = "https://docs.openclaw.ai";
+const DOCS_ROOT_PATH_SEGMENTS = new Set([
+  "agent-runtime-architecture",
+  "announcements",
+  "auth-credential-semantics",
+  "automation",
+  "channels",
+  "ci",
+  "clawhub",
+  "cli",
+  "concepts",
+  "date-time",
+  "debug",
+  "diagnostics",
+  "gateway",
+  "help",
+  "install",
+  "logging",
+  "network",
+  "nodes",
+  "openclaw-agent-runtime",
+  "platforms",
+  "plugins",
+  "prose",
+  "providers",
+  "reference",
+  "security",
+  "start",
+  "tools",
+  "vps",
+  "web",
+]);
+const CONTROL_UI_APP_PATHS = new Set([
+  "/activity",
+  "/agents",
+  "/ai-agents",
+  "/appearance",
+  "/automation",
+  "/channels",
+  "/chat",
+  "/communications",
+  "/config",
+  "/cron",
+  "/debug",
+  "/dreaming",
+  "/dreams",
+  "/infrastructure",
+  "/instances",
+  "/logs",
+  "/mcp",
+  "/nodes",
+  "/overview",
+  "/sessions",
+  "/skills",
+  "/skills/workshop",
+  "/usage",
+  "/workboard",
+]);
 const TAIL_LINK_BLUR_CLASS = "chat-link-tail-blur";
 const FENCE_OPEN_RE = /^[ \t]{0,3}(`{3,}|~{3,})/;
 const FENCE_CONTAINER_PREFIX_RE = /^[ \t]{0,3}(?:(?:>\s?)|(?:(?:[-+*]|\d{1,9}[.)])[ \t]+))/;
@@ -143,6 +201,22 @@ function isHostLocalFileHref(href: string): boolean {
   return HOST_LOCAL_FILE_HREF_RE.test(href.trim());
 }
 
+function normalizeDocsRootHref(href: string): string | null {
+  if (!href.startsWith("/") || href.startsWith("//")) {
+    return null;
+  }
+  const parsed = new URL(href, DOCS_BASE_URL);
+  const normalizedPath = parsed.pathname.replace(/\/+$/, "") || "/";
+  if (CONTROL_UI_APP_PATHS.has(normalizedPath) || normalizedPath.startsWith("/api/")) {
+    return null;
+  }
+  const firstSegment = normalizedPath.split("/").find(Boolean);
+  if (!firstSegment || !DOCS_ROOT_PATH_SEGMENTS.has(firstSegment)) {
+    return null;
+  }
+  return `${DOCS_BASE_URL}${parsed.pathname}${parsed.search}${parsed.hash}`;
+}
+
 function installHooks() {
   if (hooksInstalled) {
     return;
@@ -176,6 +250,11 @@ function installHooks() {
       // javascript: by default. This is defense-in-depth.
     }
 
+    const normalizedDocsHref = normalizeDocsRootHref(href);
+    if (normalizedDocsHref) {
+      node.setAttribute("href", normalizedDocsHref);
+    }
+
     node.setAttribute("rel", "noreferrer noopener");
     node.setAttribute("target", "_blank");
     if (normalizeLowercaseStringOrEmpty(href).includes("tail")) {
