From baef09ca1b3ef846c12a3d20301d21653392cf2f Mon Sep 17 00:00:00 2001
From: James <james.hartley@estuary.dev>
Date: Tue, 7 Apr 2026 14:32:54 +1000
Subject: [PATCH] ci: fix docs preview slug for relative frontmatter slugs

Docusaurus resolves relative slugs (no leading /) from the file's
directory. e.g. `slug: installation` in getting-started/installation.md
becomes /getting-started/installation, not /installation.

The preview link script was prepending / directly, producing the wrong
URL for files with relative slugs. Caught on #2827.
---
 .github/workflows/docs-ci-previews.yaml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/docs-ci-previews.yaml b/.github/workflows/docs-ci-previews.yaml
index b4ba2a4b234..3dd6b134a06 100644
--- a/.github/workflows/docs-ci-previews.yaml
+++ b/.github/workflows/docs-ci-previews.yaml
@@ -82,6 +82,15 @@ jobs:
               const match = content.match(/^slug:\s*(.+)$/m);
               if (match) {
                 slug = match[1].trim().replace(/['"]/g, '');
+                // Relative slugs (no leading /) are resolved from the file's directory,
+                // matching Docusaurus behaviour. e.g. slug: installation in
+                // getting-started/installation.md → /getting-started/installation
+                if (!slug.startsWith('/')) {
+                  const parts = f.replace('site/docs/', '').split('/');
+                  parts.pop();
+                  const dir = parts.join('/');
+                  slug = dir ? `/${dir}/${slug}` : `/${slug}`;
+                }
               }
               if (!slug) {
                 slug = '/' + f
@@ -89,7 +98,6 @@ jobs:
                   .replace(/\/README\.md$/, '/')
                   .replace(/\.md$/, '/');
               }
-              if (!slug.startsWith('/')) slug = '/' + slug;
               return `- [${slug}](${base}${slug})`;
             });