{title}
diff --git a/src/components/mdx/ProductCards.tsx b/src/components/mdx/ProductCards.tsx
index 38f0f7d03..9e58f5646 100644
--- a/src/components/mdx/ProductCards.tsx
+++ b/src/components/mdx/ProductCards.tsx
@@ -1,5 +1,6 @@
import Link from 'next/link';
import {CustomLink} from './CustomLink';
+import {withBasePath} from '@/lib/utils';
export function ProductCards({children}: {children: React.ReactNode}) {
return (
@@ -29,7 +30,11 @@ export function ProductCard({
{/* eslint-disable-next-line @next/next/no-img-element -- Small MDX icons do not need image optimization. */}
- 
+ })
diff --git a/src/components/mdx/ZoomableImage.tsx b/src/components/mdx/ZoomableImage.tsx
index 1ad752aea..883e4f5ee 100644
--- a/src/components/mdx/ZoomableImage.tsx
+++ b/src/components/mdx/ZoomableImage.tsx
@@ -1,10 +1,20 @@
'use client';
import {useCallback, useEffect, useState} from 'react';
+import {withBasePath} from '@/lib/utils';
interface ZoomableImageProps extends React.ImgHTMLAttributes {}
-export function ZoomableImage({className, alt, ...props}: ZoomableImageProps) {
+export function ZoomableImage({
+ className,
+ alt,
+ src,
+ ...rest
+}: ZoomableImageProps) {
+ const props = {
+ ...rest,
+ src: typeof src === 'string' ? withBasePath(src) : src
+ };
const [isOpen, setIsOpen] = useState(false);
const openModal = useCallback(() => setIsOpen(true), []);
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index 065c19661..4018927aa 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -4,3 +4,12 @@ import {twMerge} from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
+
+// Production serves the site under /docs (basePath in next.config.js). next/link
+// adds it to hrefs, but ![]()
and next/image do not, so a root-relative path
+// to a file in public/ 404s on sourcegraph.com unless prefixed here.
+export function withBasePath(url: string) {
+ const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
+ const isRootRelative = url.startsWith('/') && !url.startsWith('//');
+ return isRootRelative ? `${basePath}${url}` : url;
+}
From 76da6a502fdd9c94d4b1dc800ae9505476017e90 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 02:15:24 -0600
Subject: [PATCH 02/11] cspell: allow hrefs
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
cspell-allow-list.txt | 1 +
1 file changed, 1 insertion(+)
diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index 00ef52265..f3fdb47a7 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -241,6 +241,7 @@ horsegraph
horsten
hostmatcher
hostpath
+hrefs
HSTS
httptest
huggingface
From 68901e11f3374911bbc52bdc8b07aa499b05fe86 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 02:45:42 -0600
Subject: [PATCH 03/11] site: serve every deployment under /docs
Previews and local dev served at / while production served at /docs, so
a root-relative ![]()
only 404d after deploy. Use basePath /docs
everywhere; the / -> /docs redirect from #1955 now applies to every
deployment. Update the tooling that assumed previews had no basePath.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
.amp/services.yaml | 4 ++--
.github/workflows/preview-links.yml | 4 ++--
AGENTS.md | 12 +++++++++++-
README.md | 4 ++--
dev/verify-links-live.mjs | 7 +++----
next.config.js | 18 +++++++-----------
src/lib/utils.ts | 6 +++---
7 files changed, 30 insertions(+), 25 deletions(-)
diff --git a/.amp/services.yaml b/.amp/services.yaml
index 87e947eb5..73d0ae63a 100644
--- a/.amp/services.yaml
+++ b/.amp/services.yaml
@@ -4,7 +4,7 @@ services:
port: 31420
env:
NODE_OPTIONS: --max-old-space-size=3072
- health: /agentic-batch-changes
+ health: /docs/agentic-batch-changes
portal:
- url: /agentic-batch-changes
+ url: /docs/agentic-batch-changes
title: Sourcegraph Docs
diff --git a/.github/workflows/preview-links.yml b/.github/workflows/preview-links.yml
index 70c688e0d..c4447b8f9 100644
--- a/.github/workflows/preview-links.yml
+++ b/.github/workflows/preview-links.yml
@@ -60,11 +60,11 @@ jobs:
});
// Mirror contentlayer's flattenedPath: docs/.mdx -> /,
- // with a trailing /index dropped. Preview deployments have no basePath.
+ // with a trailing /index dropped, under the /docs basePath.
const pages = files
.filter(f => f.filename.startsWith('docs/') && f.filename.endsWith('.mdx') && f.status !== 'removed')
.map(f => f.filename.slice('docs/'.length, -'.mdx'.length).replace(/^index$/, '').replace(/\/index$/, ''))
- .map(path => ({path, url: `${previewUrl}/${path}`}));
+ .map(path => ({path, url: `${previewUrl}/docs/${path}`}));
if (pages.length === 0) {
core.info(`PR #${pr.number} changes no docs pages; not commenting.`);
diff --git a/AGENTS.md b/AGENTS.md
index 8ae767663..b3a6ddfc2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,7 +32,7 @@
linking the job log, instead of failing the PR: an empty report says nothing
about the PR
- **Prove changed links resolve on a deploy**:
- `node dev/verify-links-live.mjs --site ` prints a
+ `node dev/verify-links-live.mjs --site /docs` prints a
Markdown table for the PR description
- **Spell check**: `.github/workflows/spellcheck.yml` runs
`dev/check-spelling.mjs` on the lines a PR adds plus its title and
@@ -92,3 +92,13 @@ next run.
(From a manifest), install it, copy its
Bot User OAuth Token into the secret, and `/invite @Vercel build log` to the
channel.
+
+
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+
diff --git a/README.md b/README.md
index 398d259ba..dd6064ea3 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ Next, run the development server:
pnpm run dev
```
-Finally, open [`http://localhost:3000`](http://localhost:3000) in your browser
+Finally, open [`http://localhost:3000/docs`](http://localhost:3000/docs) in your browser
to view the website.
## Writing and contributing to Sourcegraph Docs
@@ -225,7 +225,7 @@ instructions visit
As you make changes to the documentation, the development server will
automatically update. Review your changes by navigating to
-`http://localhost:3000` in your browser.
+`http://localhost:3000/docs` in your browser.
### Previewing Vercel Deployments
diff --git a/dev/verify-links-live.mjs b/dev/verify-links-live.mjs
index 7f4434a3e..b39d32f4b 100644
--- a/dev/verify-links-live.mjs
+++ b/dev/verify-links-live.mjs
@@ -13,11 +13,10 @@
// Prints a Markdown table to paste into a PR. Old links point at --old-site so
// reviewers can see the current breakage.
//
-// node dev/verify-links-live.mjs --site https://.vercel.app [--old-site https://sourcegraph.com/docs] [--base origin/main]
+// node dev/verify-links-live.mjs --site https://.vercel.app/docs [--old-site https://sourcegraph.com/docs] [--base origin/main]
//
-// Production serves under https://sourcegraph.com/docs (basePath in
-// next.config.js); Vercel previews serve at the root, so pass the full prefix
-// in --site.
+// Every deployment serves under /docs (basePath in next.config.js), so --site
+// includes that prefix.
import { execSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
diff --git a/next.config.js b/next.config.js
index 941a822af..84aca2adc 100644
--- a/next.config.js
+++ b/next.config.js
@@ -2,12 +2,10 @@ const {PHASE_DEVELOPMENT_SERVER} = require('next/constants');
const {withContentlayer} = require('next-contentlayer2');
/** @type {import('next').NextConfig} */
-// in prod, we serve the docs from sourcegraph.com/docs, and this requires special config on the GFE side
-// in preview/development, this is not necessary.
-//
-// VERCEL_ENV is a system env var set by Vercel
-// https://vercel.com/docs/projects/environment-variables/system-environment-variables
-const basePath = process.env.VERCEL_ENV === 'production' ? '/docs' : '';
+// sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
+// same basePath so that a root-relative URL which 404s in production also 404s
+// there, instead of only breaking after deploy.
+const basePath = '/docs';
const nextConfig = {
reactStrictMode: true,
@@ -19,12 +17,10 @@ const nextConfig = {
env: {
NEXT_PUBLIC_DOCS_BASE_PATH: basePath
},
- // With basePath set, nothing serves `/`, so the *.vercel.app deployment URL
- // that Vercel links from Slack / GitHub 404s. sourcegraph.com never proxies
- // `/` to us, so this only affects visitors opening that raw URL. Stay on the
- // same host so they see this exact deployment, not whatever is live.
+ // Nothing serves `/`, so the deployment URLs Vercel links from Slack / GitHub
+ // and http://localhost:3000 would 404. sourcegraph.com never proxies `/` to
+ // us. Stay on the same host so visitors see this exact deployment.
async redirects() {
- if (!basePath) return [];
return [
{
source: '/',
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index 4018927aa..fb935217b 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -5,9 +5,9 @@ export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
-// Production serves the site under /docs (basePath in next.config.js). next/link
-// adds it to hrefs, but ![]()
and next/image do not, so a root-relative path
-// to a file in public/ 404s on sourcegraph.com unless prefixed here.
+// The site is served under /docs (basePath in next.config.js). next/link adds it
+// to hrefs, but ![]()
and next/image do not, so a root-relative path to a
+// file in public/ 404s unless prefixed here.
export function withBasePath(url: string) {
const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
const isRootRelative = url.startsWith('/') && !url.startsWith('//');
From ca00492efeafdfd1305735613860e0b66e03e581 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:07:29 -0600
Subject: [PATCH 04/11] site: one DOCS_BASE_PATH constant; drop
NEXT_PUBLIC_DOCS_BASE_PATH
basePath is declared once, in docs.config.js. next.config.js reads it for
routing; everything that builds a URL Next does not prefix (img src, a href,
fetch, metadata, proxy redirects) goes through withBasePath or reads the
constant, instead of nine copies of process.env.NEXT_PUBLIC_DOCS_BASE_PATH
or a hardcoded '/docs'.
proxy.ts: request.nextUrl.pathname already excludes the basePath, so the
path.replace('/docs', '') was a no-op that would have mangled any real
path containing '/docs'. Removed.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
docs.config.js | 5 ++-
next.config.js | 13 ++-----
src/app/[...slug]/page.tsx | 3 +-
src/app/layout.tsx | 5 +--
src/app/page.tsx | 3 +-
src/components/Logo.tsx | 8 ++---
src/components/NotFoundLinks.tsx | 8 ++---
src/components/ReleasesTable.tsx | 4 +--
src/components/Toc.tsx | 4 +--
src/components/search/Search.tsx | 7 ++--
.../search/docsearch/NoResultsScreen.tsx | 5 ++-
.../search/docsearch/StartScreen.tsx | 5 ++-
src/lib/utils.ts | 9 +++--
src/proxy.ts | 36 +++++++++----------
14 files changed, 54 insertions(+), 61 deletions(-)
diff --git a/docs.config.js b/docs.config.js
index f5ca0dd01..f5b04f4b9 100644
--- a/docs.config.js
+++ b/docs.config.js
@@ -1,5 +1,8 @@
const config = {
- DOCS_LATEST_VERSION: '8.0'
+ DOCS_LATEST_VERSION: '8.0',
+ // sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
+ // same basePath so a root-relative URL that 404s in production 404s there too.
+ DOCS_BASE_PATH: '/docs'
};
module.exports = config;
diff --git a/next.config.js b/next.config.js
index 84aca2adc..eea492352 100644
--- a/next.config.js
+++ b/next.config.js
@@ -1,22 +1,15 @@
const {PHASE_DEVELOPMENT_SERVER} = require('next/constants');
const {withContentlayer} = require('next-contentlayer2');
+const {DOCS_BASE_PATH} = require('./docs.config.js');
/** @type {import('next').NextConfig} */
-// sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
-// same basePath so that a root-relative URL which 404s in production also 404s
-// there, instead of only breaking after deploy.
-const basePath = '/docs';
-
const nextConfig = {
reactStrictMode: true,
- basePath,
+ basePath: DOCS_BASE_PATH,
// Orb portals proxy the dev server through a different hostname.
allowedDevOrigins: process.env.PUBLIC_URL
? [new URL(process.env.PUBLIC_URL).hostname]
: [],
- env: {
- NEXT_PUBLIC_DOCS_BASE_PATH: basePath
- },
// Nothing serves `/`, so the deployment URLs Vercel links from Slack / GitHub
// and http://localhost:3000 would 404. sourcegraph.com never proxies `/` to
// us. Stay on the same host so visitors see this exact deployment.
@@ -24,7 +17,7 @@ const nextConfig = {
return [
{
source: '/',
- destination: basePath,
+ destination: DOCS_BASE_PATH,
basePath: false,
permanent: false
}
diff --git a/src/app/[...slug]/page.tsx b/src/app/[...slug]/page.tsx
index 3bc78c815..095d5871c 100644
--- a/src/app/[...slug]/page.tsx
+++ b/src/app/[...slug]/page.tsx
@@ -4,6 +4,7 @@ import {PreviewGuard} from '@/components/PreviewGuard';
import {PrevNextLinks} from '@/components/PrevNextLinks';
import {Prose} from '@/components/Prose';
import {TableOfContents} from '@/components/Toc';
+import {withBasePath} from '@/lib/utils';
import {allPosts} from 'contentlayer/generated';
import {getMDXComponent} from 'next-contentlayer2/hooks';
import {notFound} from 'next/navigation';
@@ -28,7 +29,7 @@ export const generateMetadata = async ({params}: Props) => {
const post = allPosts.find(post => post._raw.flattenedPath === path);
if (post && post.headings && post.headings.length > 0) {
const title = post.headings[0].title;
- const ogImageUrl = `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/${path}`;
+ const ogImageUrl = withBasePath(`/api/og/${path}`);
return {
title,
// The root layout's canonical is the landing page; without this
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 3408ec9c0..97a20de64 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,6 +1,7 @@
import {Providers} from '@/app/providers';
import {Layout} from '@/components/Layout';
import {TECHNICAL_CHANGELOG_RSS_URL} from '@/data/constants';
+import {withBasePath} from '@/lib/utils';
import clsx from 'clsx';
import config from 'docs.config';
import {type Metadata} from 'next';
@@ -26,11 +27,11 @@ export const metadata: Metadata = {
canonical: '/docs'
},
openGraph: {
- images: [{url: `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/index`, width: 1200, height: 630}]
+ images: [{url: withBasePath('/api/og/index'), width: 1200, height: 630}]
},
twitter: {
card: 'summary_large_image',
- images: [{url: `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/index`, width: 1200, height: 630}]
+ images: [{url: withBasePath('/api/og/index'), width: 1200, height: 630}]
}
};
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 01a78b0fe..11cd0c712 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,11 +1,12 @@
import MdxComponents from '@/components/MdxComponents';
import {Prose} from '@/components/Prose';
+import {withBasePath} from '@/lib/utils';
import {allPosts} from 'contentlayer/generated';
import {getMDXComponent} from 'next-contentlayer2/hooks';
import {notFound} from 'next/navigation';
export const generateMetadata = () => {
- const ogImageUrl = `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/index`;
+ const ogImageUrl = withBasePath('/api/og/index');
return {
openGraph: {
images: [{url: ogImageUrl, width: 1200, height: 630}]
diff --git a/src/components/Logo.tsx b/src/components/Logo.tsx
index 2acb056e7..dc6119f74 100644
--- a/src/components/Logo.tsx
+++ b/src/components/Logo.tsx
@@ -1,18 +1,18 @@
-export function Logo(props: React.ComponentPropsWithoutRef<'svg'>) {
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
+import {withBasePath} from '@/lib/utils';
+export function Logo(props: React.ComponentPropsWithoutRef<'svg'>) {
return (
<>
{/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */}
{/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */}
diff --git a/src/components/NotFoundLinks.tsx b/src/components/NotFoundLinks.tsx
index 9d532cb7b..0d0230562 100644
--- a/src/components/NotFoundLinks.tsx
+++ b/src/components/NotFoundLinks.tsx
@@ -4,6 +4,7 @@ import {usePreviousPathname} from '@/components/PreviousPathname';
import Link from 'next/link';
import {usePathname} from 'next/navigation';
import {useEffect, useMemo, useState} from 'react';
+import config from 'docs.config';
const linkClassName =
'text-sm font-medium text-slate-900 hover:underline dark:text-white';
@@ -22,9 +23,6 @@ function nearestExistingAncestor(
return null;
}
-// Production serves the docs under /docs (basePath in next.config.js).
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
interface PageLink {
href: string;
pathname: string;
@@ -39,8 +37,8 @@ function docsReferrer(): PageLink | null {
if (!document.referrer) return null;
const referrer = new URL(document.referrer);
if (referrer.origin !== window.location.origin) return null;
- if (!referrer.pathname.startsWith(`${basePath}/`)) return null;
- const pathname = referrer.pathname.slice(basePath.length);
+ if (!referrer.pathname.startsWith(`${config.DOCS_BASE_PATH}/`)) return null;
+ const pathname = referrer.pathname.slice(config.DOCS_BASE_PATH.length);
// The home link already covers the root.
if (pathname === '/') return null;
return {href: pathname + referrer.search + referrer.hash, pathname};
diff --git a/src/components/ReleasesTable.tsx b/src/components/ReleasesTable.tsx
index 383830a37..bb81bc5f3 100644
--- a/src/components/ReleasesTable.tsx
+++ b/src/components/ReleasesTable.tsx
@@ -2,6 +2,7 @@
import {useEffect, useState} from 'react';
import Link from 'next/link';
+import {withBasePath} from '@/lib/utils';
type Release = {
id: number;
@@ -31,8 +32,7 @@ export function SupportedReleasesTable() {
const [error, setError] = useState(null);
useEffect(() => {
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
- fetch(`${basePath}/api/releases`)
+ fetch(withBasePath('/api/releases'))
.then(res => {
if (!res.ok) throw new Error('Failed to fetch releases');
return res.json();
diff --git a/src/components/Toc.tsx b/src/components/Toc.tsx
index 9d037c197..c62cae983 100644
--- a/src/components/Toc.tsx
+++ b/src/components/Toc.tsx
@@ -4,6 +4,7 @@ import clsx from 'clsx';
import Link from 'next/link';
import {useParams} from 'next/navigation';
import {useCallback, useEffect, useState} from 'react';
+import {withBasePath} from '@/lib/utils';
import {ClipboardIcon} from './icons/ClipboardIcon';
import {PencilIcon} from './icons/PencilIcon';
import {DocumentIcon} from './icons/DocumentIcon';
@@ -29,7 +30,6 @@ export function TableOfContents({headings, rawMarkdown, editPath}: Props) {
let [currentSection, setCurrentSection] = useState(headings[0]?.id);
const [copied, setCopied] = useState(false);
const params: ParamsType = useParams();
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
const handleCopyPage = useCallback(async () => {
if (!rawMarkdown) return;
@@ -168,7 +168,7 @@ export function TableOfContents({headings, rawMarkdown, editPath}: Props) {
url.startsWith(PROD_DOCS_URL_PREFIX)
- ? basePath + url.slice(PROD_DOCS_URL_PREFIX.length)
+ ? withBasePath(url.slice(PROD_DOCS_URL_PREFIX.length))
: url;
const hitPriority = (hit: DocSearchHit): number => {
diff --git a/src/components/search/docsearch/NoResultsScreen.tsx b/src/components/search/docsearch/NoResultsScreen.tsx
index a378d7040..feeff3bda 100644
--- a/src/components/search/docsearch/NoResultsScreen.tsx
+++ b/src/components/search/docsearch/NoResultsScreen.tsx
@@ -1,5 +1,6 @@
import React from 'react';
import {productFilterLinks} from '../../../data/search';
+import {withBasePath} from '@/lib/utils';
import type {ScreenStateProps} from './ScreenState';
import type {InternalDocSearchHit} from './types';
@@ -18,8 +19,6 @@ type NoResultsScreenProps = Omit<
translations?: NoResultsScreenTranslations;
};
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
export function NoResultsScreen({
translations = {},
...props
@@ -56,7 +55,7 @@ export function NoResultsScreen({
{suggestion.title}
diff --git a/src/components/search/docsearch/StartScreen.tsx b/src/components/search/docsearch/StartScreen.tsx
index 6bd1003c0..b4c6925b3 100644
--- a/src/components/search/docsearch/StartScreen.tsx
+++ b/src/components/search/docsearch/StartScreen.tsx
@@ -2,6 +2,7 @@ import {RecentIcon} from './icons/RecentIcon';
import {ResetIcon} from './icons/ResetIcon';
import {StarIcon} from './icons/StarIcon';
import {curatedSearchSuggestions} from '../../../data/search';
+import {withBasePath} from '@/lib/utils';
import {Results} from './Results';
import type {ScreenStateProps} from './ScreenState';
@@ -24,8 +25,6 @@ type StartScreenProps = Omit<
translations?: StartScreenTranslations;
};
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
function Suggestions() {
return (
{curatedSearchSuggestions.map(suggestion => (
-
+
{suggestion.title}
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index fb935217b..67b891dc9 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -1,15 +1,14 @@
import {type ClassValue, clsx} from 'clsx';
+import config from 'docs.config';
import {twMerge} from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
-// The site is served under /docs (basePath in next.config.js). next/link adds it
-// to hrefs, but ![]()
and next/image do not, so a root-relative path to a
-// file in public/ 404s unless prefixed here.
+// next/link and routing add the basePath; ![]()
, , fetch() and
+// metadata URLs do not, so root-relative URLs for those go through here.
export function withBasePath(url: string) {
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
const isRootRelative = url.startsWith('/') && !url.startsWith('//');
- return isRootRelative ? `${basePath}${url}` : url;
+ return isRootRelative ? `${config.DOCS_BASE_PATH}${url}` : url;
}
diff --git a/src/proxy.ts b/src/proxy.ts
index f3d1e3cda..f944986d2 100644
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@ -48,19 +48,19 @@ function createRedirectUrl(
}
// Handle relative paths
- const basePath = '/docs';
+ const base = `${request.nextUrl.origin}${docsConfig.DOCS_BASE_PATH}`;
return destination.startsWith('/')
- ? `${request.nextUrl.origin}${basePath}${destination}`
- : `${request.nextUrl.origin}${basePath}/${destination}`;
+ ? `${base}${destination}`
+ : `${base}/${destination}`;
}
export function proxy(request: NextRequest) {
+ // nextUrl.pathname excludes basePath, so /docs/x arrives here as /x.
const path = request.nextUrl.pathname;
- const pathWithoutBase = path.replace('/docs', '');
// Handle .md suffix - return raw markdown
- if (pathWithoutBase.endsWith('.md')) {
- const docPath = pathWithoutBase.replace(/\.md$/, '');
+ if (path.endsWith('.md')) {
+ const docPath = path.replace(/\.md$/, '');
const url = request.nextUrl.clone();
url.pathname = `/api/md${docPath}`;
return NextResponse.rewrite(url);
@@ -68,7 +68,7 @@ export function proxy(request: NextRequest) {
// Handle base redirects from redirects.ts
const redirect = updatedRedirectsData.find(
- (r: any) => r.source === pathWithoutBase
+ (r: any) => r.source === path
);
if (redirect) {
return NextResponse.redirect(
@@ -77,7 +77,7 @@ export function proxy(request: NextRequest) {
}
// Handle latest version without path - redirect to main docs
- const latestVersionOnlyMatch = pathWithoutBase.match(
+ const latestVersionOnlyMatch = path.match(
`^\/(?:v\/|@)${docsConfig.DOCS_LATEST_VERSION}\/?$`
);
if (latestVersionOnlyMatch) {
@@ -85,7 +85,7 @@ export function proxy(request: NextRequest) {
}
// Handle version without slug - both /v/X.Y and @X.Y formats (for non-latest versions)
- const versionOnlyMatch = pathWithoutBase.match(
+ const versionOnlyMatch = path.match(
/^\/(?:v\/|@)(\d+\.\d+)\/?$/
);
if (
@@ -98,47 +98,47 @@ export function proxy(request: NextRequest) {
}
// Handle version-specific redirects
- if (pathWithoutBase.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`)) {
+ if (path.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`)) {
return NextResponse.redirect(
createRedirectUrl(
request,
`https://sourcegraph.com/docs/:slug*`,
- pathWithoutBase
+ path
)
);
}
- if (pathWithoutBase.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)) {
+ if (path.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)) {
return NextResponse.redirect(
createRedirectUrl(
request,
`https://sourcegraph.com/docs/:slug*`,
- pathWithoutBase
+ path
)
);
}
- const versionMatch = pathWithoutBase.match(/^\/v\/(\d+\.\d+)\/(.*)/);
+ const versionMatch = path.match(/^\/v\/(\d+\.\d+)\/(.*)/);
if (versionMatch) {
return NextResponse.redirect(
createRedirectUrl(
request,
'https://:version.sourcegraph.com/:slug*',
- pathWithoutBase
+ path
)
);
}
- const atVersionMatch = pathWithoutBase.match(/^\/@(\d+\.\d+)\/(.*)/);
+ const atVersionMatch = path.match(/^\/@(\d+\.\d+)\/(.*)/);
if (atVersionMatch) {
return NextResponse.redirect(
createRedirectUrl(
request,
'https://:version.sourcegraph.com/:slug*',
- pathWithoutBase
+ path
)
);
}
- if (pathWithoutBase === '/changelog.rss')
+ if (path === '/changelog.rss')
return NextResponse.redirect(TECHNICAL_CHANGELOG_RSS_URL);
return NextResponse.next();
From 411d2b2a104cee0b81a12c3d310f68db0ae122ee Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:08:45 -0600
Subject: [PATCH 05/11] proxy: keep latest-version redirects on the current
deployment
/v//x and /@/x redirected to https://sourcegraph.com/docs/x
even from a preview or local dev, so a reviewer testing those paths on a
preview silently landed on production. The current deployment serves the
latest version, so redirect to its own origin + DOCS_BASE_PATH instead.
Also merges the identical /v/ and /@ branches.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
src/proxy.ts | 22 +++++++++-------------
1 file changed, 9 insertions(+), 13 deletions(-)
diff --git a/src/proxy.ts b/src/proxy.ts
index f944986d2..77770f16b 100644
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@ -81,7 +81,9 @@ export function proxy(request: NextRequest) {
`^\/(?:v\/|@)${docsConfig.DOCS_LATEST_VERSION}\/?$`
);
if (latestVersionOnlyMatch) {
- return NextResponse.redirect(`https://sourcegraph.com/docs`);
+ return NextResponse.redirect(
+ `${request.nextUrl.origin}${docsConfig.DOCS_BASE_PATH}`
+ );
}
// Handle version without slug - both /v/X.Y and @X.Y formats (for non-latest versions)
@@ -97,21 +99,15 @@ export function proxy(request: NextRequest) {
);
}
- // Handle version-specific redirects
- if (path.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`)) {
- return NextResponse.redirect(
- createRedirectUrl(
- request,
- `https://sourcegraph.com/docs/:slug*`,
- path
- )
- );
- }
- if (path.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)) {
+ // Latest version with a slug: this deployment serves it, so stay here.
+ if (
+ path.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`) ||
+ path.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)
+ ) {
return NextResponse.redirect(
createRedirectUrl(
request,
- `https://sourcegraph.com/docs/:slug*`,
+ `${request.nextUrl.origin}${docsConfig.DOCS_BASE_PATH}/:slug*`,
path
)
);
From 6b9f3cb7bcd83b52ba4673d1fb88bb568368b800 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:27:27 -0600
Subject: [PATCH 06/11] site: derive every /docs and production URL from
docs.config.js
The basePath has moved three times. Next time, change DOCS_BASE_PATH (and
DOCS_PROD_ORIGIN if the host moves) in docs.config.js and nothing else:
- versions.ts, api/versions, VersionSelector, sitemap, robots, Search and
the layout canonical/metadataBase read DOCS_BASE_PATH / DOCS_PROD_URL
instead of spelling out /docs or https://sourcegraph.com/docs
- check-redirects, check-links (self-link regex) and verify-links-live
import docs.config.js
- preview-links.yml checks out the PR's docs.config.js to build page URLs
- search.ts searchDocumentsPath is root-relative like every public/ path;
it is only a flag for writing public/search.json
.amp/services.yaml is YAML and keeps its literal path, with a note.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
.amp/services.yaml | 1 +
.github/workflows/preview-links.yml | 11 +++++++++--
dev/algolia-index.mjs | 4 ++--
dev/check-links.mjs | 19 +++++++++++++------
dev/check-redirects.mjs | 29 ++++++++++++++++-------------
dev/verify-links-live.mjs | 9 +++++----
docs.config.js | 13 ++++++++++---
src/app/[...slug]/page.tsx | 2 +-
src/app/api/versions/route.ts | 3 ++-
src/app/layout.tsx | 4 ++--
src/app/robots.ts | 3 ++-
src/app/sitemap.ts | 7 +++----
src/components/VersionSelector.tsx | 3 ++-
src/components/search/Search.tsx | 13 ++++++-------
src/data/search.ts | 4 +++-
src/data/versions.ts | 2 +-
16 files changed, 78 insertions(+), 49 deletions(-)
diff --git a/.amp/services.yaml b/.amp/services.yaml
index 73d0ae63a..e6614b0a4 100644
--- a/.amp/services.yaml
+++ b/.amp/services.yaml
@@ -4,6 +4,7 @@ services:
port: 31420
env:
NODE_OPTIONS: --max-old-space-size=3072
+ # YAML cannot read DOCS_BASE_PATH from docs.config.js; keep these in step.
health: /docs/agentic-batch-changes
portal:
url: /docs/agentic-batch-changes
diff --git a/.github/workflows/preview-links.yml b/.github/workflows/preview-links.yml
index c4447b8f9..20854b43f 100644
--- a/.github/workflows/preview-links.yml
+++ b/.github/workflows/preview-links.yml
@@ -29,6 +29,12 @@ jobs:
if: github.event.client_payload.environment != 'production'
runs-on: ubuntu-latest
steps:
+ # The PR's own docs.config.js, for the basePath the preview serves under.
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.client_payload.git.sha || inputs.sha }}
+ sparse-checkout: docs.config.js
+ sparse-checkout-cone-mode: false
- uses: actions/github-script@v7
env:
PREVIEW_URL: ${{ github.event.client_payload.url || inputs.url }}
@@ -36,6 +42,7 @@ jobs:
with:
script: |
const {PREVIEW_URL, COMMIT_SHA} = process.env;
+ const {DOCS_BASE_PATH} = require(`${process.env.GITHUB_WORKSPACE}/docs.config.js`);
if (!PREVIEW_URL || !/^[0-9a-f]{40}$/i.test(COMMIT_SHA ?? '')) {
core.setFailed(`Need a preview URL and a full commit SHA; got url=${JSON.stringify(PREVIEW_URL)} sha=${JSON.stringify(COMMIT_SHA)}. `
+ `Vercel sends these as client_payload.url and client_payload.git.sha; workflow_dispatch takes them as the url and sha inputs.`);
@@ -60,11 +67,11 @@ jobs:
});
// Mirror contentlayer's flattenedPath: docs/.mdx -> /,
- // with a trailing /index dropped, under the /docs basePath.
+ // with a trailing /index dropped, under the basePath.
const pages = files
.filter(f => f.filename.startsWith('docs/') && f.filename.endsWith('.mdx') && f.status !== 'removed')
.map(f => f.filename.slice('docs/'.length, -'.mdx'.length).replace(/^index$/, '').replace(/\/index$/, ''))
- .map(path => ({path, url: `${previewUrl}/docs/${path}`}));
+ .map(path => ({path, url: `${previewUrl}${DOCS_BASE_PATH}/${path}`}));
if (pages.length === 0) {
core.info(`PR #${pr.number} changes no docs pages; not commenting.`);
diff --git a/dev/algolia-index.mjs b/dev/algolia-index.mjs
index a7ebed8c7..b8f47e83d 100644
--- a/dev/algolia-index.mjs
+++ b/dev/algolia-index.mjs
@@ -25,12 +25,12 @@ import fs from 'node:fs';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import GithubSlugger from 'github-slugger';
+import config from '../docs.config.js';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const generatedDir = path.join(root, '.contentlayer/generated/Post');
const outDir = path.join(root, '.algolia');
-const SITE_URL = 'https://sourcegraph.com/docs';
const DEFAULT_INDEX = 'sourcegraph_docs';
const DEFAULT_APP_ID = 'JSZOJ0ZYVG';
// Consecutive paragraphs under the same heading are merged into chunks of up to
@@ -282,7 +282,7 @@ function contentHash(content) {
function buildPageRecords(post, owner, deduplication) {
const url = post.url;
- const pageUrl = SITE_URL + url;
+ const pageUrl = config.DOCS_PROD_URL + url;
const slugger = new GithubSlugger();
const pageRank = Math.round((post.seoPriority ?? 0.5) * 100);
const records = [];
diff --git a/dev/check-links.mjs b/dev/check-links.mjs
index f9fd80857..74620146a 100644
--- a/dev/check-links.mjs
+++ b/dev/check-links.mjs
@@ -46,6 +46,7 @@ import fs from 'fs';
import path from 'path';
import GithubSlugger from 'github-slugger';
import { fileURLToPath, pathToFileURL } from 'url';
+import config from '../docs.config.js';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
@@ -279,11 +280,17 @@ function extractLinks(content, filePath) {
}
// Absolute links to this site, in every form the docs have used: http or https,
-// scheme-relative, www., the legacy docs.sourcegraph.com host, or sourcegraph.com/docs.
-// Links pinned to an old version (/@5.1/..., /v/5.1/...) are external: the
-// middleware sends them to that version's own site (5.1.sourcegraph.com), whose
-// pages are not in this repo, so only --check-external can validate them.
-const SELF_LINK_REGEX = /^(?:https?:)?\/\/(?:www\.)?(?:docs\.sourcegraph\.com|sourcegraph\.com\/docs)(?=[/#?]|$)(?!\/@|\/v\/)/i;
+// scheme-relative, www., the legacy docs.sourcegraph.com host, or the production
+// URL from docs.config.js. Links pinned to an old version (/@5.1/..., /v/5.1/...)
+// are external: the middleware sends them to that version's own site
+// (5.1.sourcegraph.com), whose pages are not in this repo, so only
+// --check-external can validate them.
+const escapeRegExp = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const PROD_HOST_AND_PATH = config.DOCS_PROD_URL.replace(/^https?:\/\//, '');
+const SELF_LINK_REGEX = new RegExp(
+ `^(?:https?:)?//(?:www\\.)?(?:docs\\.sourcegraph\\.com|${escapeRegExp(PROD_HOST_AND_PATH)})(?=[/#?]|$)(?!/@|/v/)`,
+ 'i'
+);
export function isSelfLink(url) {
return SELF_LINK_REGEX.test(url);
@@ -580,7 +587,7 @@ function markdownFindingList(findings) {
const ABSOLUTE_LINKS_ADVICE =
'Write links on this site as relative paths (`/admin/config/site-config`), ' +
- 'not `https://sourcegraph.com/docs/…`: absolute links leave the preview ' +
+ `not \`${config.DOCS_PROD_URL}/…\`: absolute links leave the preview ` +
'deployment and local dev server, and hide moved pages behind redirects.';
// Body for a pull request comment. With --diff, findings are split into
diff --git a/dev/check-redirects.mjs b/dev/check-redirects.mjs
index f84d0e191..32d038c21 100644
--- a/dev/check-redirects.mjs
+++ b/dev/check-redirects.mjs
@@ -10,8 +10,8 @@
* - the source has no #fragment: browsers never send fragments, so such an
* entry can never match
* - the source has no earlier entry: the middleware uses the first match only
- * - neither path starts with /docs: the middleware strips that prefix from
- * requests and adds it to destinations
+ * - neither path starts with the basePath (docs.config.js): Next strips it
+ * from requests and the middleware adds it to destinations
* - the destination is a page, not another redirect
* - the destination page exists under docs/ (or is a file under public/)
* - when the destination has a #fragment, the heading exists on that page
@@ -39,11 +39,13 @@ import path from 'path';
import vm from 'vm';
import {fileURLToPath} from 'url';
import {extractHeadings, listFiles, routeFor} from './check-links.mjs';
+import config from '../docs.config.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const args = process.argv.slice(2);
const ROOT_DIR = path.resolve(flagValue('--root') ?? path.dirname(__dirname));
+const BASE_PATH = config.DOCS_BASE_PATH;
const FORMAT = flagValue('--format') ?? 'text';
const BASELINE_FILE = flagValue('--baseline');
const LINK_BASE = flagValue('--link-base')?.replace(/\/$/, '');
@@ -72,12 +74,12 @@ const PROBLEM = {
'If the redirect destination has a #fragment, it takes precedence, otherwise if the customer ' +
"clicked a link which has a #fragment, it'll be kept and tried on the destination page."
},
- docsPrefix: {
- heading: 'Source or destination starts with /docs',
+ basePathPrefix: {
+ heading: `Source or destination starts with ${BASE_PATH}`,
fix:
- 'Write paths without the /docs prefix. The site removes /docs from the requested URL before ' +
- 'matching sources, and adds it back in front of the destination, so a /docs/... source never ' +
- 'matches and a /docs/... destination lands on /docs/docs/....'
+ `Write paths without the ${BASE_PATH} prefix. The site removes ${BASE_PATH} from the requested URL before ` +
+ `matching sources, and adds it back in front of the destination, so a ${BASE_PATH}/... source never ` +
+ `matches and a ${BASE_PATH}/... destination lands on ${BASE_PATH}${BASE_PATH}/....`
},
duplicateSource: {
heading:
@@ -198,7 +200,8 @@ function findBrokenRedirects(redirects, headingsByRoute) {
const report = (redirect, problem, {detail, fix} = {}) =>
findings.push({...redirect, problem: problem.heading, detail, fix});
const withoutFragment = url => url.split('#')[0];
- const withoutDocsPrefix = url => url.replace(/^\/docs(?=\/)/, '');
+ const withoutBasePath = url =>
+ url.startsWith(`${BASE_PATH}/`) ? url.slice(BASE_PATH.length) : url;
const isRedirect = pathname =>
firstBySource.has(pathname) && !headingsByRoute.has(pathname);
@@ -220,13 +223,13 @@ function findBrokenRedirects(redirects, headingsByRoute) {
report(redirect, PROBLEM.shadowsPage);
}
if (
- source.pathname.startsWith('/docs/') ||
- redirect.destination.startsWith('/docs/')
+ source.pathname.startsWith(`${BASE_PATH}/`) ||
+ redirect.destination.startsWith(`${BASE_PATH}/`)
) {
- report(redirect, PROBLEM.docsPrefix, {
+ report(redirect, PROBLEM.basePathPrefix, {
fix: {
- source: withoutDocsPrefix(redirect.source),
- destination: withoutDocsPrefix(redirect.destination)
+ source: withoutBasePath(redirect.source),
+ destination: withoutBasePath(redirect.destination)
}
});
continue;
diff --git a/dev/verify-links-live.mjs b/dev/verify-links-live.mjs
index b39d32f4b..f2120d68e 100644
--- a/dev/verify-links-live.mjs
+++ b/dev/verify-links-live.mjs
@@ -15,20 +15,21 @@
//
// node dev/verify-links-live.mjs --site https://.vercel.app/docs [--old-site https://sourcegraph.com/docs] [--base origin/main]
//
-// Every deployment serves under /docs (basePath in next.config.js), so --site
-// includes that prefix.
+// Every deployment serves under the basePath (docs.config.js), so --site
+// includes that prefix. Both default to production.
import { execSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { extractHeadings } from './check-links.mjs';
+import config from '../docs.config.js';
const args = process.argv.slice(2);
const argValue = (flag, fallback) => {
const index = args.indexOf(flag);
return index === -1 ? fallback : args[index + 1];
};
-const SITE = argValue('--site', 'https://sourcegraph.com/docs').replace(/\/$/, '');
-const OLD_SITE = argValue('--old-site', 'https://sourcegraph.com/docs').replace(/\/$/, '');
+const SITE = argValue('--site', config.DOCS_PROD_URL).replace(/\/$/, '');
+const OLD_SITE = argValue('--old-site', config.DOCS_PROD_URL).replace(/\/$/, '');
const BASE_REF = argValue('--base', 'origin/main');
const LINK = /\]\(([^)\s]+)\)|href=["']([^"']+)["']/g;
diff --git a/docs.config.js b/docs.config.js
index f5b04f4b9..51c5d04be 100644
--- a/docs.config.js
+++ b/docs.config.js
@@ -1,8 +1,15 @@
+// sourcegraph.com proxies DOCS_BASE_PATH/* to this site. Previews and local dev
+// use the same basePath so a root-relative URL that 404s in production 404s
+// there too. To move the site, change DOCS_BASE_PATH here and the load balancer
+// rule in sourcegraph/infrastructure; nothing else spells the path out.
+const DOCS_BASE_PATH = '/docs';
+const DOCS_PROD_ORIGIN = 'https://sourcegraph.com';
+
const config = {
DOCS_LATEST_VERSION: '8.0',
- // sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
- // same basePath so a root-relative URL that 404s in production 404s there too.
- DOCS_BASE_PATH: '/docs'
+ DOCS_BASE_PATH,
+ DOCS_PROD_ORIGIN,
+ DOCS_PROD_URL: `${DOCS_PROD_ORIGIN}${DOCS_BASE_PATH}`
};
module.exports = config;
diff --git a/src/app/[...slug]/page.tsx b/src/app/[...slug]/page.tsx
index 095d5871c..831eab97d 100644
--- a/src/app/[...slug]/page.tsx
+++ b/src/app/[...slug]/page.tsx
@@ -35,7 +35,7 @@ export const generateMetadata = async ({params}: Props) => {
// The root layout's canonical is the landing page; without this
// override every docs page tells search engines it is a duplicate
// of https://sourcegraph.com/docs.
- alternates: {canonical: `/docs${post.url}`},
+ alternates: {canonical: withBasePath(post.url)},
openGraph: {
images: [{url: ogImageUrl, width: 1200, height: 630}]
},
diff --git a/src/app/api/versions/route.ts b/src/app/api/versions/route.ts
index 686d5c24e..b87d9c031 100644
--- a/src/app/api/versions/route.ts
+++ b/src/app/api/versions/route.ts
@@ -1,4 +1,5 @@
import {versions} from '@/data/versions';
+import config from 'docs.config';
import {NextResponse} from 'next/server';
// Next 15+ no longer caches GET handlers by default; the version list is
@@ -9,7 +10,7 @@ export function GET() {
return NextResponse.json(
versions.map((version, index) =>
index === 0
- ? {...version, url: 'https://sourcegraph.com/docs'}
+ ? {...version, url: config.DOCS_PROD_URL}
: version
),
{
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 97a20de64..3a696a774 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -12,7 +12,7 @@ import {Suspense} from 'react';
import '@/styles/tailwind.css';
export const metadata: Metadata = {
- metadataBase: new URL('https://sourcegraph.com'),
+ metadataBase: new URL(config.DOCS_PROD_ORIGIN),
title: {
template: '%s - Sourcegraph docs',
default: 'Sourcegraph docs'
@@ -24,7 +24,7 @@ export const metadata: Metadata = {
'docsearch:version': `v${config.DOCS_LATEST_VERSION}`
},
alternates: {
- canonical: '/docs'
+ canonical: config.DOCS_BASE_PATH
},
openGraph: {
images: [{url: withBasePath('/api/og/index'), width: 1200, height: 630}]
diff --git a/src/app/robots.ts b/src/app/robots.ts
index 35d3bdba1..ed87f84e1 100644
--- a/src/app/robots.ts
+++ b/src/app/robots.ts
@@ -1,4 +1,5 @@
import {MetadataRoute} from 'next';
+import config from 'docs.config';
export default async function robots(): Promise {
return {
@@ -6,6 +7,6 @@ export default async function robots(): Promise {
userAgent: '*',
allow: '/'
},
- sitemap: 'https://sourcegraph.com/docs/sitemap.xml'
+ sitemap: `${config.DOCS_PROD_URL}/sitemap.xml`
};
}
diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts
index 618ceb52f..968493c84 100644
--- a/src/app/sitemap.ts
+++ b/src/app/sitemap.ts
@@ -1,12 +1,11 @@
import {MetadataRoute} from 'next';
import {allPosts} from 'contentlayer/generated';
+import config from 'docs.config';
export default async function sitemap(): Promise {
- const baseUrl = 'https://sourcegraph.com/docs';
-
const links: MetadataRoute.Sitemap = [
{
- url: baseUrl,
+ url: config.DOCS_PROD_URL,
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 1.0
@@ -18,7 +17,7 @@ export default async function sitemap(): Promise {
.forEach(post => {
const priority = post.seoPriority;
links.push({
- url: `${baseUrl}${post.url}`,
+ url: `${config.DOCS_PROD_URL}${post.url}`,
lastModified: post.date ? new Date(post.date) : new Date(),
changeFrequency: 'weekly',
...(priority !== undefined && priority !== 0.5 && {priority})
diff --git a/src/components/VersionSelector.tsx b/src/components/VersionSelector.tsx
index 90b34b93c..4fcfa8cbe 100644
--- a/src/components/VersionSelector.tsx
+++ b/src/components/VersionSelector.tsx
@@ -8,13 +8,14 @@ import {
ChevronDownIcon
} from '@heroicons/react/20/solid';
import clsx from 'clsx';
+import config from 'docs.config';
import Link from 'next/link';
import {usePathname} from 'next/navigation';
import {Fragment, useEffect, useState} from 'react';
const versionsUrl =
process.env.NEXT_PUBLIC_DOCS_VERSIONS_URL ??
- 'https://sourcegraph.com/docs/api/versions';
+ `${config.DOCS_PROD_URL}/api/versions`;
function isVersion(value: unknown): value is VersionI {
if (typeof value !== 'object' || value === null) return false;
diff --git a/src/components/search/Search.tsx b/src/components/search/Search.tsx
index 4d7a3de22..b1418d17d 100644
--- a/src/components/search/Search.tsx
+++ b/src/components/search/Search.tsx
@@ -1,4 +1,5 @@
import {withBasePath} from '@/lib/utils';
+import config from 'docs.config';
import {productFilters, searchMetadata} from '../../data/search';
import {DocSearch} from './docsearch/DocSearch';
import type {DocSearchHit} from './docsearch/types';
@@ -6,14 +7,12 @@ import './docsearch/docsearch.css';
// import '@docsearch/css';
-// The Algolia crawler indexes production, so every hit URL is absolute
-// (https://sourcegraph.com/docs/...). Rewrite them to root-relative paths so
-// results stay on whichever deployment is being viewed.
-const PROD_DOCS_URL_PREFIX = 'https://sourcegraph.com/docs';
-
+// The Algolia crawler indexes production, so every hit URL is absolute.
+// Rewrite them to root-relative paths so results stay on whichever deployment
+// is being viewed.
const toLocalUrl = (url: string): string =>
- url.startsWith(PROD_DOCS_URL_PREFIX)
- ? withBasePath(url.slice(PROD_DOCS_URL_PREFIX.length))
+ url.startsWith(config.DOCS_PROD_URL)
+ ? withBasePath(url.slice(config.DOCS_PROD_URL.length))
: url;
const hitPriority = (hit: DocSearchHit): number => {
diff --git a/src/data/search.ts b/src/data/search.ts
index 2cda44b00..e50883263 100644
--- a/src/data/search.ts
+++ b/src/data/search.ts
@@ -67,7 +67,9 @@ export const curatedSearchSuggestions = [
export const searchMetadata = {
provider: 'kbar',
kbarConfig: {
- searchDocumentsPath: '/docs/search.json' // path to load documents to search
+ // Root-relative like every public/ path; contentlayer.config.ts only checks
+ // it is set before writing public/search.json.
+ searchDocumentsPath: '/search.json'
},
// For Algolia
// provider: 'algolia',
diff --git a/src/data/versions.ts b/src/data/versions.ts
index f36a7442c..db5dcc035 100644
--- a/src/data/versions.ts
+++ b/src/data/versions.ts
@@ -11,7 +11,7 @@ export const versions: VersionI[] = [
{
name: `v${config.DOCS_LATEST_VERSION}`,
label: 'latest',
- url: '/docs'
+ url: config.DOCS_BASE_PATH
},
{
name: 'v7.7',
From 04645b7b2c0dd82b90569135a6fe8a622c811bc6 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:56:45 -0600
Subject: [PATCH 07/11] chore: drop the kbar search index and the dead MDX
video mapping
kbar was removed in #110; the contentlayer onSuccess hook kept writing a
725 KB public/search.json that nothing fetched. src/utils/contentlayer.ts
only existed to build that index.
MDX compiles an explicit
diff --git a/src/components/mdx/ZoomableImage.tsx b/src/components/mdx/ZoomableImage.tsx
index 1ad752aea..883e4f5ee 100644
--- a/src/components/mdx/ZoomableImage.tsx
+++ b/src/components/mdx/ZoomableImage.tsx
@@ -1,10 +1,20 @@
'use client';
import {useCallback, useEffect, useState} from 'react';
+import {withBasePath} from '@/lib/utils';
interface ZoomableImageProps extends React.ImgHTMLAttributes {}
-export function ZoomableImage({className, alt, ...props}: ZoomableImageProps) {
+export function ZoomableImage({
+ className,
+ alt,
+ src,
+ ...rest
+}: ZoomableImageProps) {
+ const props = {
+ ...rest,
+ src: typeof src === 'string' ? withBasePath(src) : src
+ };
const [isOpen, setIsOpen] = useState(false);
const openModal = useCallback(() => setIsOpen(true), []);
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index 065c19661..4018927aa 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -4,3 +4,12 @@ import {twMerge} from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
+
+// Production serves the site under /docs (basePath in next.config.js). next/link
+// adds it to hrefs, but ![]()
and next/image do not, so a root-relative path
+// to a file in public/ 404s on sourcegraph.com unless prefixed here.
+export function withBasePath(url: string) {
+ const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
+ const isRootRelative = url.startsWith('/') && !url.startsWith('//');
+ return isRootRelative ? `${basePath}${url}` : url;
+}
From 76da6a502fdd9c94d4b1dc800ae9505476017e90 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 02:15:24 -0600
Subject: [PATCH 02/11] cspell: allow hrefs
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
cspell-allow-list.txt | 1 +
1 file changed, 1 insertion(+)
diff --git a/cspell-allow-list.txt b/cspell-allow-list.txt
index 00ef52265..f3fdb47a7 100644
--- a/cspell-allow-list.txt
+++ b/cspell-allow-list.txt
@@ -241,6 +241,7 @@ horsegraph
horsten
hostmatcher
hostpath
+hrefs
HSTS
httptest
huggingface
From 68901e11f3374911bbc52bdc8b07aa499b05fe86 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 02:45:42 -0600
Subject: [PATCH 03/11] site: serve every deployment under /docs
Previews and local dev served at / while production served at /docs, so
a root-relative ![]()
only 404d after deploy. Use basePath /docs
everywhere; the / -> /docs redirect from #1955 now applies to every
deployment. Update the tooling that assumed previews had no basePath.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
.amp/services.yaml | 4 ++--
.github/workflows/preview-links.yml | 4 ++--
AGENTS.md | 12 +++++++++++-
README.md | 4 ++--
dev/verify-links-live.mjs | 7 +++----
next.config.js | 18 +++++++-----------
src/lib/utils.ts | 6 +++---
7 files changed, 30 insertions(+), 25 deletions(-)
diff --git a/.amp/services.yaml b/.amp/services.yaml
index 87e947eb5..73d0ae63a 100644
--- a/.amp/services.yaml
+++ b/.amp/services.yaml
@@ -4,7 +4,7 @@ services:
port: 31420
env:
NODE_OPTIONS: --max-old-space-size=3072
- health: /agentic-batch-changes
+ health: /docs/agentic-batch-changes
portal:
- url: /agentic-batch-changes
+ url: /docs/agentic-batch-changes
title: Sourcegraph Docs
diff --git a/.github/workflows/preview-links.yml b/.github/workflows/preview-links.yml
index 70c688e0d..c4447b8f9 100644
--- a/.github/workflows/preview-links.yml
+++ b/.github/workflows/preview-links.yml
@@ -60,11 +60,11 @@ jobs:
});
// Mirror contentlayer's flattenedPath: docs/.mdx -> /,
- // with a trailing /index dropped. Preview deployments have no basePath.
+ // with a trailing /index dropped, under the /docs basePath.
const pages = files
.filter(f => f.filename.startsWith('docs/') && f.filename.endsWith('.mdx') && f.status !== 'removed')
.map(f => f.filename.slice('docs/'.length, -'.mdx'.length).replace(/^index$/, '').replace(/\/index$/, ''))
- .map(path => ({path, url: `${previewUrl}/${path}`}));
+ .map(path => ({path, url: `${previewUrl}/docs/${path}`}));
if (pages.length === 0) {
core.info(`PR #${pr.number} changes no docs pages; not commenting.`);
diff --git a/AGENTS.md b/AGENTS.md
index 8ae767663..b3a6ddfc2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,7 +32,7 @@
linking the job log, instead of failing the PR: an empty report says nothing
about the PR
- **Prove changed links resolve on a deploy**:
- `node dev/verify-links-live.mjs --site ` prints a
+ `node dev/verify-links-live.mjs --site /docs` prints a
Markdown table for the PR description
- **Spell check**: `.github/workflows/spellcheck.yml` runs
`dev/check-spelling.mjs` on the lines a PR adds plus its title and
@@ -92,3 +92,13 @@ next run.
(From a manifest), install it, copy its
Bot User OAuth Token into the secret, and `/invite @Vercel build log` to the
channel.
+
+
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+
diff --git a/README.md b/README.md
index 398d259ba..dd6064ea3 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,7 @@ Next, run the development server:
pnpm run dev
```
-Finally, open [`http://localhost:3000`](http://localhost:3000) in your browser
+Finally, open [`http://localhost:3000/docs`](http://localhost:3000/docs) in your browser
to view the website.
## Writing and contributing to Sourcegraph Docs
@@ -225,7 +225,7 @@ instructions visit
As you make changes to the documentation, the development server will
automatically update. Review your changes by navigating to
-`http://localhost:3000` in your browser.
+`http://localhost:3000/docs` in your browser.
### Previewing Vercel Deployments
diff --git a/dev/verify-links-live.mjs b/dev/verify-links-live.mjs
index 7f4434a3e..b39d32f4b 100644
--- a/dev/verify-links-live.mjs
+++ b/dev/verify-links-live.mjs
@@ -13,11 +13,10 @@
// Prints a Markdown table to paste into a PR. Old links point at --old-site so
// reviewers can see the current breakage.
//
-// node dev/verify-links-live.mjs --site https://.vercel.app [--old-site https://sourcegraph.com/docs] [--base origin/main]
+// node dev/verify-links-live.mjs --site https://.vercel.app/docs [--old-site https://sourcegraph.com/docs] [--base origin/main]
//
-// Production serves under https://sourcegraph.com/docs (basePath in
-// next.config.js); Vercel previews serve at the root, so pass the full prefix
-// in --site.
+// Every deployment serves under /docs (basePath in next.config.js), so --site
+// includes that prefix.
import { execSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
diff --git a/next.config.js b/next.config.js
index 941a822af..84aca2adc 100644
--- a/next.config.js
+++ b/next.config.js
@@ -2,12 +2,10 @@ const {PHASE_DEVELOPMENT_SERVER} = require('next/constants');
const {withContentlayer} = require('next-contentlayer2');
/** @type {import('next').NextConfig} */
-// in prod, we serve the docs from sourcegraph.com/docs, and this requires special config on the GFE side
-// in preview/development, this is not necessary.
-//
-// VERCEL_ENV is a system env var set by Vercel
-// https://vercel.com/docs/projects/environment-variables/system-environment-variables
-const basePath = process.env.VERCEL_ENV === 'production' ? '/docs' : '';
+// sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
+// same basePath so that a root-relative URL which 404s in production also 404s
+// there, instead of only breaking after deploy.
+const basePath = '/docs';
const nextConfig = {
reactStrictMode: true,
@@ -19,12 +17,10 @@ const nextConfig = {
env: {
NEXT_PUBLIC_DOCS_BASE_PATH: basePath
},
- // With basePath set, nothing serves `/`, so the *.vercel.app deployment URL
- // that Vercel links from Slack / GitHub 404s. sourcegraph.com never proxies
- // `/` to us, so this only affects visitors opening that raw URL. Stay on the
- // same host so they see this exact deployment, not whatever is live.
+ // Nothing serves `/`, so the deployment URLs Vercel links from Slack / GitHub
+ // and http://localhost:3000 would 404. sourcegraph.com never proxies `/` to
+ // us. Stay on the same host so visitors see this exact deployment.
async redirects() {
- if (!basePath) return [];
return [
{
source: '/',
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index 4018927aa..fb935217b 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -5,9 +5,9 @@ export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
-// Production serves the site under /docs (basePath in next.config.js). next/link
-// adds it to hrefs, but ![]()
and next/image do not, so a root-relative path
-// to a file in public/ 404s on sourcegraph.com unless prefixed here.
+// The site is served under /docs (basePath in next.config.js). next/link adds it
+// to hrefs, but ![]()
and next/image do not, so a root-relative path to a
+// file in public/ 404s unless prefixed here.
export function withBasePath(url: string) {
const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
const isRootRelative = url.startsWith('/') && !url.startsWith('//');
From ca00492efeafdfd1305735613860e0b66e03e581 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:07:29 -0600
Subject: [PATCH 04/11] site: one DOCS_BASE_PATH constant; drop
NEXT_PUBLIC_DOCS_BASE_PATH
basePath is declared once, in docs.config.js. next.config.js reads it for
routing; everything that builds a URL Next does not prefix (img src, a href,
fetch, metadata, proxy redirects) goes through withBasePath or reads the
constant, instead of nine copies of process.env.NEXT_PUBLIC_DOCS_BASE_PATH
or a hardcoded '/docs'.
proxy.ts: request.nextUrl.pathname already excludes the basePath, so the
path.replace('/docs', '') was a no-op that would have mangled any real
path containing '/docs'. Removed.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
docs.config.js | 5 ++-
next.config.js | 13 ++-----
src/app/[...slug]/page.tsx | 3 +-
src/app/layout.tsx | 5 +--
src/app/page.tsx | 3 +-
src/components/Logo.tsx | 8 ++---
src/components/NotFoundLinks.tsx | 8 ++---
src/components/ReleasesTable.tsx | 4 +--
src/components/Toc.tsx | 4 +--
src/components/search/Search.tsx | 7 ++--
.../search/docsearch/NoResultsScreen.tsx | 5 ++-
.../search/docsearch/StartScreen.tsx | 5 ++-
src/lib/utils.ts | 9 +++--
src/proxy.ts | 36 +++++++++----------
14 files changed, 54 insertions(+), 61 deletions(-)
diff --git a/docs.config.js b/docs.config.js
index f5ca0dd01..f5b04f4b9 100644
--- a/docs.config.js
+++ b/docs.config.js
@@ -1,5 +1,8 @@
const config = {
- DOCS_LATEST_VERSION: '8.0'
+ DOCS_LATEST_VERSION: '8.0',
+ // sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
+ // same basePath so a root-relative URL that 404s in production 404s there too.
+ DOCS_BASE_PATH: '/docs'
};
module.exports = config;
diff --git a/next.config.js b/next.config.js
index 84aca2adc..eea492352 100644
--- a/next.config.js
+++ b/next.config.js
@@ -1,22 +1,15 @@
const {PHASE_DEVELOPMENT_SERVER} = require('next/constants');
const {withContentlayer} = require('next-contentlayer2');
+const {DOCS_BASE_PATH} = require('./docs.config.js');
/** @type {import('next').NextConfig} */
-// sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
-// same basePath so that a root-relative URL which 404s in production also 404s
-// there, instead of only breaking after deploy.
-const basePath = '/docs';
-
const nextConfig = {
reactStrictMode: true,
- basePath,
+ basePath: DOCS_BASE_PATH,
// Orb portals proxy the dev server through a different hostname.
allowedDevOrigins: process.env.PUBLIC_URL
? [new URL(process.env.PUBLIC_URL).hostname]
: [],
- env: {
- NEXT_PUBLIC_DOCS_BASE_PATH: basePath
- },
// Nothing serves `/`, so the deployment URLs Vercel links from Slack / GitHub
// and http://localhost:3000 would 404. sourcegraph.com never proxies `/` to
// us. Stay on the same host so visitors see this exact deployment.
@@ -24,7 +17,7 @@ const nextConfig = {
return [
{
source: '/',
- destination: basePath,
+ destination: DOCS_BASE_PATH,
basePath: false,
permanent: false
}
diff --git a/src/app/[...slug]/page.tsx b/src/app/[...slug]/page.tsx
index 3bc78c815..095d5871c 100644
--- a/src/app/[...slug]/page.tsx
+++ b/src/app/[...slug]/page.tsx
@@ -4,6 +4,7 @@ import {PreviewGuard} from '@/components/PreviewGuard';
import {PrevNextLinks} from '@/components/PrevNextLinks';
import {Prose} from '@/components/Prose';
import {TableOfContents} from '@/components/Toc';
+import {withBasePath} from '@/lib/utils';
import {allPosts} from 'contentlayer/generated';
import {getMDXComponent} from 'next-contentlayer2/hooks';
import {notFound} from 'next/navigation';
@@ -28,7 +29,7 @@ export const generateMetadata = async ({params}: Props) => {
const post = allPosts.find(post => post._raw.flattenedPath === path);
if (post && post.headings && post.headings.length > 0) {
const title = post.headings[0].title;
- const ogImageUrl = `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/${path}`;
+ const ogImageUrl = withBasePath(`/api/og/${path}`);
return {
title,
// The root layout's canonical is the landing page; without this
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 3408ec9c0..97a20de64 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -1,6 +1,7 @@
import {Providers} from '@/app/providers';
import {Layout} from '@/components/Layout';
import {TECHNICAL_CHANGELOG_RSS_URL} from '@/data/constants';
+import {withBasePath} from '@/lib/utils';
import clsx from 'clsx';
import config from 'docs.config';
import {type Metadata} from 'next';
@@ -26,11 +27,11 @@ export const metadata: Metadata = {
canonical: '/docs'
},
openGraph: {
- images: [{url: `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/index`, width: 1200, height: 630}]
+ images: [{url: withBasePath('/api/og/index'), width: 1200, height: 630}]
},
twitter: {
card: 'summary_large_image',
- images: [{url: `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/index`, width: 1200, height: 630}]
+ images: [{url: withBasePath('/api/og/index'), width: 1200, height: 630}]
}
};
diff --git a/src/app/page.tsx b/src/app/page.tsx
index 01a78b0fe..11cd0c712 100644
--- a/src/app/page.tsx
+++ b/src/app/page.tsx
@@ -1,11 +1,12 @@
import MdxComponents from '@/components/MdxComponents';
import {Prose} from '@/components/Prose';
+import {withBasePath} from '@/lib/utils';
import {allPosts} from 'contentlayer/generated';
import {getMDXComponent} from 'next-contentlayer2/hooks';
import {notFound} from 'next/navigation';
export const generateMetadata = () => {
- const ogImageUrl = `${process.env.NEXT_PUBLIC_DOCS_BASE_PATH || ''}/api/og/index`;
+ const ogImageUrl = withBasePath('/api/og/index');
return {
openGraph: {
images: [{url: ogImageUrl, width: 1200, height: 630}]
diff --git a/src/components/Logo.tsx b/src/components/Logo.tsx
index 2acb056e7..dc6119f74 100644
--- a/src/components/Logo.tsx
+++ b/src/components/Logo.tsx
@@ -1,18 +1,18 @@
-export function Logo(props: React.ComponentPropsWithoutRef<'svg'>) {
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
+import {withBasePath} from '@/lib/utils';
+export function Logo(props: React.ComponentPropsWithoutRef<'svg'>) {
return (
<>
{/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */}
{/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */}
diff --git a/src/components/NotFoundLinks.tsx b/src/components/NotFoundLinks.tsx
index 9d532cb7b..0d0230562 100644
--- a/src/components/NotFoundLinks.tsx
+++ b/src/components/NotFoundLinks.tsx
@@ -4,6 +4,7 @@ import {usePreviousPathname} from '@/components/PreviousPathname';
import Link from 'next/link';
import {usePathname} from 'next/navigation';
import {useEffect, useMemo, useState} from 'react';
+import config from 'docs.config';
const linkClassName =
'text-sm font-medium text-slate-900 hover:underline dark:text-white';
@@ -22,9 +23,6 @@ function nearestExistingAncestor(
return null;
}
-// Production serves the docs under /docs (basePath in next.config.js).
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
interface PageLink {
href: string;
pathname: string;
@@ -39,8 +37,8 @@ function docsReferrer(): PageLink | null {
if (!document.referrer) return null;
const referrer = new URL(document.referrer);
if (referrer.origin !== window.location.origin) return null;
- if (!referrer.pathname.startsWith(`${basePath}/`)) return null;
- const pathname = referrer.pathname.slice(basePath.length);
+ if (!referrer.pathname.startsWith(`${config.DOCS_BASE_PATH}/`)) return null;
+ const pathname = referrer.pathname.slice(config.DOCS_BASE_PATH.length);
// The home link already covers the root.
if (pathname === '/') return null;
return {href: pathname + referrer.search + referrer.hash, pathname};
diff --git a/src/components/ReleasesTable.tsx b/src/components/ReleasesTable.tsx
index 383830a37..bb81bc5f3 100644
--- a/src/components/ReleasesTable.tsx
+++ b/src/components/ReleasesTable.tsx
@@ -2,6 +2,7 @@
import {useEffect, useState} from 'react';
import Link from 'next/link';
+import {withBasePath} from '@/lib/utils';
type Release = {
id: number;
@@ -31,8 +32,7 @@ export function SupportedReleasesTable() {
const [error, setError] = useState(null);
useEffect(() => {
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
- fetch(`${basePath}/api/releases`)
+ fetch(withBasePath('/api/releases'))
.then(res => {
if (!res.ok) throw new Error('Failed to fetch releases');
return res.json();
diff --git a/src/components/Toc.tsx b/src/components/Toc.tsx
index 9d037c197..c62cae983 100644
--- a/src/components/Toc.tsx
+++ b/src/components/Toc.tsx
@@ -4,6 +4,7 @@ import clsx from 'clsx';
import Link from 'next/link';
import {useParams} from 'next/navigation';
import {useCallback, useEffect, useState} from 'react';
+import {withBasePath} from '@/lib/utils';
import {ClipboardIcon} from './icons/ClipboardIcon';
import {PencilIcon} from './icons/PencilIcon';
import {DocumentIcon} from './icons/DocumentIcon';
@@ -29,7 +30,6 @@ export function TableOfContents({headings, rawMarkdown, editPath}: Props) {
let [currentSection, setCurrentSection] = useState(headings[0]?.id);
const [copied, setCopied] = useState(false);
const params: ParamsType = useParams();
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
const handleCopyPage = useCallback(async () => {
if (!rawMarkdown) return;
@@ -168,7 +168,7 @@ export function TableOfContents({headings, rawMarkdown, editPath}: Props) {
{/* eslint-disable-next-line @next/next/no-img-element -- SVG logos do not need image optimization. */}
diff --git a/src/components/NotFoundLinks.tsx b/src/components/NotFoundLinks.tsx
index 9d532cb7b..0d0230562 100644
--- a/src/components/NotFoundLinks.tsx
+++ b/src/components/NotFoundLinks.tsx
@@ -4,6 +4,7 @@ import {usePreviousPathname} from '@/components/PreviousPathname';
import Link from 'next/link';
import {usePathname} from 'next/navigation';
import {useEffect, useMemo, useState} from 'react';
+import config from 'docs.config';
const linkClassName =
'text-sm font-medium text-slate-900 hover:underline dark:text-white';
@@ -22,9 +23,6 @@ function nearestExistingAncestor(
return null;
}
-// Production serves the docs under /docs (basePath in next.config.js).
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
interface PageLink {
href: string;
pathname: string;
@@ -39,8 +37,8 @@ function docsReferrer(): PageLink | null {
if (!document.referrer) return null;
const referrer = new URL(document.referrer);
if (referrer.origin !== window.location.origin) return null;
- if (!referrer.pathname.startsWith(`${basePath}/`)) return null;
- const pathname = referrer.pathname.slice(basePath.length);
+ if (!referrer.pathname.startsWith(`${config.DOCS_BASE_PATH}/`)) return null;
+ const pathname = referrer.pathname.slice(config.DOCS_BASE_PATH.length);
// The home link already covers the root.
if (pathname === '/') return null;
return {href: pathname + referrer.search + referrer.hash, pathname};
diff --git a/src/components/ReleasesTable.tsx b/src/components/ReleasesTable.tsx
index 383830a37..bb81bc5f3 100644
--- a/src/components/ReleasesTable.tsx
+++ b/src/components/ReleasesTable.tsx
@@ -2,6 +2,7 @@
import {useEffect, useState} from 'react';
import Link from 'next/link';
+import {withBasePath} from '@/lib/utils';
type Release = {
id: number;
@@ -31,8 +32,7 @@ export function SupportedReleasesTable() {
const [error, setError] = useState
url.startsWith(PROD_DOCS_URL_PREFIX)
- ? basePath + url.slice(PROD_DOCS_URL_PREFIX.length)
+ ? withBasePath(url.slice(PROD_DOCS_URL_PREFIX.length))
: url;
const hitPriority = (hit: DocSearchHit): number => {
diff --git a/src/components/search/docsearch/NoResultsScreen.tsx b/src/components/search/docsearch/NoResultsScreen.tsx
index a378d7040..feeff3bda 100644
--- a/src/components/search/docsearch/NoResultsScreen.tsx
+++ b/src/components/search/docsearch/NoResultsScreen.tsx
@@ -1,5 +1,6 @@
import React from 'react';
import {productFilterLinks} from '../../../data/search';
+import {withBasePath} from '@/lib/utils';
import type {ScreenStateProps} from './ScreenState';
import type {InternalDocSearchHit} from './types';
@@ -18,8 +19,6 @@ type NoResultsScreenProps = Omit<
translations?: NoResultsScreenTranslations;
};
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
export function NoResultsScreen({
translations = {},
...props
@@ -56,7 +55,7 @@ export function NoResultsScreen({
{suggestion.title}
diff --git a/src/components/search/docsearch/StartScreen.tsx b/src/components/search/docsearch/StartScreen.tsx
index 6bd1003c0..b4c6925b3 100644
--- a/src/components/search/docsearch/StartScreen.tsx
+++ b/src/components/search/docsearch/StartScreen.tsx
@@ -2,6 +2,7 @@ import {RecentIcon} from './icons/RecentIcon';
import {ResetIcon} from './icons/ResetIcon';
import {StarIcon} from './icons/StarIcon';
import {curatedSearchSuggestions} from '../../../data/search';
+import {withBasePath} from '@/lib/utils';
import {Results} from './Results';
import type {ScreenStateProps} from './ScreenState';
@@ -24,8 +25,6 @@ type StartScreenProps = Omit<
translations?: StartScreenTranslations;
};
-const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
-
function Suggestions() {
return (
{curatedSearchSuggestions.map(suggestion => (
-
+
{suggestion.title}
diff --git a/src/lib/utils.ts b/src/lib/utils.ts
index fb935217b..67b891dc9 100644
--- a/src/lib/utils.ts
+++ b/src/lib/utils.ts
@@ -1,15 +1,14 @@
import {type ClassValue, clsx} from 'clsx';
+import config from 'docs.config';
import {twMerge} from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
-// The site is served under /docs (basePath in next.config.js). next/link adds it
-// to hrefs, but ![]()
and next/image do not, so a root-relative path to a
-// file in public/ 404s unless prefixed here.
+// next/link and routing add the basePath; ![]()
, , fetch() and
+// metadata URLs do not, so root-relative URLs for those go through here.
export function withBasePath(url: string) {
- const basePath = process.env.NEXT_PUBLIC_DOCS_BASE_PATH || '';
const isRootRelative = url.startsWith('/') && !url.startsWith('//');
- return isRootRelative ? `${basePath}${url}` : url;
+ return isRootRelative ? `${config.DOCS_BASE_PATH}${url}` : url;
}
diff --git a/src/proxy.ts b/src/proxy.ts
index f3d1e3cda..f944986d2 100644
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@ -48,19 +48,19 @@ function createRedirectUrl(
}
// Handle relative paths
- const basePath = '/docs';
+ const base = `${request.nextUrl.origin}${docsConfig.DOCS_BASE_PATH}`;
return destination.startsWith('/')
- ? `${request.nextUrl.origin}${basePath}${destination}`
- : `${request.nextUrl.origin}${basePath}/${destination}`;
+ ? `${base}${destination}`
+ : `${base}/${destination}`;
}
export function proxy(request: NextRequest) {
+ // nextUrl.pathname excludes basePath, so /docs/x arrives here as /x.
const path = request.nextUrl.pathname;
- const pathWithoutBase = path.replace('/docs', '');
// Handle .md suffix - return raw markdown
- if (pathWithoutBase.endsWith('.md')) {
- const docPath = pathWithoutBase.replace(/\.md$/, '');
+ if (path.endsWith('.md')) {
+ const docPath = path.replace(/\.md$/, '');
const url = request.nextUrl.clone();
url.pathname = `/api/md${docPath}`;
return NextResponse.rewrite(url);
@@ -68,7 +68,7 @@ export function proxy(request: NextRequest) {
// Handle base redirects from redirects.ts
const redirect = updatedRedirectsData.find(
- (r: any) => r.source === pathWithoutBase
+ (r: any) => r.source === path
);
if (redirect) {
return NextResponse.redirect(
@@ -77,7 +77,7 @@ export function proxy(request: NextRequest) {
}
// Handle latest version without path - redirect to main docs
- const latestVersionOnlyMatch = pathWithoutBase.match(
+ const latestVersionOnlyMatch = path.match(
`^\/(?:v\/|@)${docsConfig.DOCS_LATEST_VERSION}\/?$`
);
if (latestVersionOnlyMatch) {
@@ -85,7 +85,7 @@ export function proxy(request: NextRequest) {
}
// Handle version without slug - both /v/X.Y and @X.Y formats (for non-latest versions)
- const versionOnlyMatch = pathWithoutBase.match(
+ const versionOnlyMatch = path.match(
/^\/(?:v\/|@)(\d+\.\d+)\/?$/
);
if (
@@ -98,47 +98,47 @@ export function proxy(request: NextRequest) {
}
// Handle version-specific redirects
- if (pathWithoutBase.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`)) {
+ if (path.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`)) {
return NextResponse.redirect(
createRedirectUrl(
request,
`https://sourcegraph.com/docs/:slug*`,
- pathWithoutBase
+ path
)
);
}
- if (pathWithoutBase.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)) {
+ if (path.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)) {
return NextResponse.redirect(
createRedirectUrl(
request,
`https://sourcegraph.com/docs/:slug*`,
- pathWithoutBase
+ path
)
);
}
- const versionMatch = pathWithoutBase.match(/^\/v\/(\d+\.\d+)\/(.*)/);
+ const versionMatch = path.match(/^\/v\/(\d+\.\d+)\/(.*)/);
if (versionMatch) {
return NextResponse.redirect(
createRedirectUrl(
request,
'https://:version.sourcegraph.com/:slug*',
- pathWithoutBase
+ path
)
);
}
- const atVersionMatch = pathWithoutBase.match(/^\/@(\d+\.\d+)\/(.*)/);
+ const atVersionMatch = path.match(/^\/@(\d+\.\d+)\/(.*)/);
if (atVersionMatch) {
return NextResponse.redirect(
createRedirectUrl(
request,
'https://:version.sourcegraph.com/:slug*',
- pathWithoutBase
+ path
)
);
}
- if (pathWithoutBase === '/changelog.rss')
+ if (path === '/changelog.rss')
return NextResponse.redirect(TECHNICAL_CHANGELOG_RSS_URL);
return NextResponse.next();
From 411d2b2a104cee0b81a12c3d310f68db0ae122ee Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:08:45 -0600
Subject: [PATCH 05/11] proxy: keep latest-version redirects on the current
deployment
/v//x and /@/x redirected to https://sourcegraph.com/docs/x
even from a preview or local dev, so a reviewer testing those paths on a
preview silently landed on production. The current deployment serves the
latest version, so redirect to its own origin + DOCS_BASE_PATH instead.
Also merges the identical /v/ and /@ branches.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
src/proxy.ts | 22 +++++++++-------------
1 file changed, 9 insertions(+), 13 deletions(-)
diff --git a/src/proxy.ts b/src/proxy.ts
index f944986d2..77770f16b 100644
--- a/src/proxy.ts
+++ b/src/proxy.ts
@@ -81,7 +81,9 @@ export function proxy(request: NextRequest) {
`^\/(?:v\/|@)${docsConfig.DOCS_LATEST_VERSION}\/?$`
);
if (latestVersionOnlyMatch) {
- return NextResponse.redirect(`https://sourcegraph.com/docs`);
+ return NextResponse.redirect(
+ `${request.nextUrl.origin}${docsConfig.DOCS_BASE_PATH}`
+ );
}
// Handle version without slug - both /v/X.Y and @X.Y formats (for non-latest versions)
@@ -97,21 +99,15 @@ export function proxy(request: NextRequest) {
);
}
- // Handle version-specific redirects
- if (path.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`)) {
- return NextResponse.redirect(
- createRedirectUrl(
- request,
- `https://sourcegraph.com/docs/:slug*`,
- path
- )
- );
- }
- if (path.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)) {
+ // Latest version with a slug: this deployment serves it, so stay here.
+ if (
+ path.startsWith(`/v/${docsConfig.DOCS_LATEST_VERSION}/`) ||
+ path.startsWith(`/@${docsConfig.DOCS_LATEST_VERSION}/`)
+ ) {
return NextResponse.redirect(
createRedirectUrl(
request,
- `https://sourcegraph.com/docs/:slug*`,
+ `${request.nextUrl.origin}${docsConfig.DOCS_BASE_PATH}/:slug*`,
path
)
);
From 6b9f3cb7bcd83b52ba4673d1fb88bb568368b800 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:27:27 -0600
Subject: [PATCH 06/11] site: derive every /docs and production URL from
docs.config.js
The basePath has moved three times. Next time, change DOCS_BASE_PATH (and
DOCS_PROD_ORIGIN if the host moves) in docs.config.js and nothing else:
- versions.ts, api/versions, VersionSelector, sitemap, robots, Search and
the layout canonical/metadataBase read DOCS_BASE_PATH / DOCS_PROD_URL
instead of spelling out /docs or https://sourcegraph.com/docs
- check-redirects, check-links (self-link regex) and verify-links-live
import docs.config.js
- preview-links.yml checks out the PR's docs.config.js to build page URLs
- search.ts searchDocumentsPath is root-relative like every public/ path;
it is only a flag for writing public/search.json
.amp/services.yaml is YAML and keeps its literal path, with a note.
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp
---
.amp/services.yaml | 1 +
.github/workflows/preview-links.yml | 11 +++++++++--
dev/algolia-index.mjs | 4 ++--
dev/check-links.mjs | 19 +++++++++++++------
dev/check-redirects.mjs | 29 ++++++++++++++++-------------
dev/verify-links-live.mjs | 9 +++++----
docs.config.js | 13 ++++++++++---
src/app/[...slug]/page.tsx | 2 +-
src/app/api/versions/route.ts | 3 ++-
src/app/layout.tsx | 4 ++--
src/app/robots.ts | 3 ++-
src/app/sitemap.ts | 7 +++----
src/components/VersionSelector.tsx | 3 ++-
src/components/search/Search.tsx | 13 ++++++-------
src/data/search.ts | 4 +++-
src/data/versions.ts | 2 +-
16 files changed, 78 insertions(+), 49 deletions(-)
diff --git a/.amp/services.yaml b/.amp/services.yaml
index 73d0ae63a..e6614b0a4 100644
--- a/.amp/services.yaml
+++ b/.amp/services.yaml
@@ -4,6 +4,7 @@ services:
port: 31420
env:
NODE_OPTIONS: --max-old-space-size=3072
+ # YAML cannot read DOCS_BASE_PATH from docs.config.js; keep these in step.
health: /docs/agentic-batch-changes
portal:
url: /docs/agentic-batch-changes
diff --git a/.github/workflows/preview-links.yml b/.github/workflows/preview-links.yml
index c4447b8f9..20854b43f 100644
--- a/.github/workflows/preview-links.yml
+++ b/.github/workflows/preview-links.yml
@@ -29,6 +29,12 @@ jobs:
if: github.event.client_payload.environment != 'production'
runs-on: ubuntu-latest
steps:
+ # The PR's own docs.config.js, for the basePath the preview serves under.
+ - uses: actions/checkout@v4
+ with:
+ ref: ${{ github.event.client_payload.git.sha || inputs.sha }}
+ sparse-checkout: docs.config.js
+ sparse-checkout-cone-mode: false
- uses: actions/github-script@v7
env:
PREVIEW_URL: ${{ github.event.client_payload.url || inputs.url }}
@@ -36,6 +42,7 @@ jobs:
with:
script: |
const {PREVIEW_URL, COMMIT_SHA} = process.env;
+ const {DOCS_BASE_PATH} = require(`${process.env.GITHUB_WORKSPACE}/docs.config.js`);
if (!PREVIEW_URL || !/^[0-9a-f]{40}$/i.test(COMMIT_SHA ?? '')) {
core.setFailed(`Need a preview URL and a full commit SHA; got url=${JSON.stringify(PREVIEW_URL)} sha=${JSON.stringify(COMMIT_SHA)}. `
+ `Vercel sends these as client_payload.url and client_payload.git.sha; workflow_dispatch takes them as the url and sha inputs.`);
@@ -60,11 +67,11 @@ jobs:
});
// Mirror contentlayer's flattenedPath: docs/.mdx -> /,
- // with a trailing /index dropped, under the /docs basePath.
+ // with a trailing /index dropped, under the basePath.
const pages = files
.filter(f => f.filename.startsWith('docs/') && f.filename.endsWith('.mdx') && f.status !== 'removed')
.map(f => f.filename.slice('docs/'.length, -'.mdx'.length).replace(/^index$/, '').replace(/\/index$/, ''))
- .map(path => ({path, url: `${previewUrl}/docs/${path}`}));
+ .map(path => ({path, url: `${previewUrl}${DOCS_BASE_PATH}/${path}`}));
if (pages.length === 0) {
core.info(`PR #${pr.number} changes no docs pages; not commenting.`);
diff --git a/dev/algolia-index.mjs b/dev/algolia-index.mjs
index a7ebed8c7..b8f47e83d 100644
--- a/dev/algolia-index.mjs
+++ b/dev/algolia-index.mjs
@@ -25,12 +25,12 @@ import fs from 'node:fs';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import GithubSlugger from 'github-slugger';
+import config from '../docs.config.js';
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const generatedDir = path.join(root, '.contentlayer/generated/Post');
const outDir = path.join(root, '.algolia');
-const SITE_URL = 'https://sourcegraph.com/docs';
const DEFAULT_INDEX = 'sourcegraph_docs';
const DEFAULT_APP_ID = 'JSZOJ0ZYVG';
// Consecutive paragraphs under the same heading are merged into chunks of up to
@@ -282,7 +282,7 @@ function contentHash(content) {
function buildPageRecords(post, owner, deduplication) {
const url = post.url;
- const pageUrl = SITE_URL + url;
+ const pageUrl = config.DOCS_PROD_URL + url;
const slugger = new GithubSlugger();
const pageRank = Math.round((post.seoPriority ?? 0.5) * 100);
const records = [];
diff --git a/dev/check-links.mjs b/dev/check-links.mjs
index f9fd80857..74620146a 100644
--- a/dev/check-links.mjs
+++ b/dev/check-links.mjs
@@ -46,6 +46,7 @@ import fs from 'fs';
import path from 'path';
import GithubSlugger from 'github-slugger';
import { fileURLToPath, pathToFileURL } from 'url';
+import config from '../docs.config.js';
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
@@ -279,11 +280,17 @@ function extractLinks(content, filePath) {
}
// Absolute links to this site, in every form the docs have used: http or https,
-// scheme-relative, www., the legacy docs.sourcegraph.com host, or sourcegraph.com/docs.
-// Links pinned to an old version (/@5.1/..., /v/5.1/...) are external: the
-// middleware sends them to that version's own site (5.1.sourcegraph.com), whose
-// pages are not in this repo, so only --check-external can validate them.
-const SELF_LINK_REGEX = /^(?:https?:)?\/\/(?:www\.)?(?:docs\.sourcegraph\.com|sourcegraph\.com\/docs)(?=[/#?]|$)(?!\/@|\/v\/)/i;
+// scheme-relative, www., the legacy docs.sourcegraph.com host, or the production
+// URL from docs.config.js. Links pinned to an old version (/@5.1/..., /v/5.1/...)
+// are external: the middleware sends them to that version's own site
+// (5.1.sourcegraph.com), whose pages are not in this repo, so only
+// --check-external can validate them.
+const escapeRegExp = text => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const PROD_HOST_AND_PATH = config.DOCS_PROD_URL.replace(/^https?:\/\//, '');
+const SELF_LINK_REGEX = new RegExp(
+ `^(?:https?:)?//(?:www\\.)?(?:docs\\.sourcegraph\\.com|${escapeRegExp(PROD_HOST_AND_PATH)})(?=[/#?]|$)(?!/@|/v/)`,
+ 'i'
+);
export function isSelfLink(url) {
return SELF_LINK_REGEX.test(url);
@@ -580,7 +587,7 @@ function markdownFindingList(findings) {
const ABSOLUTE_LINKS_ADVICE =
'Write links on this site as relative paths (`/admin/config/site-config`), ' +
- 'not `https://sourcegraph.com/docs/…`: absolute links leave the preview ' +
+ `not \`${config.DOCS_PROD_URL}/…\`: absolute links leave the preview ` +
'deployment and local dev server, and hide moved pages behind redirects.';
// Body for a pull request comment. With --diff, findings are split into
diff --git a/dev/check-redirects.mjs b/dev/check-redirects.mjs
index f84d0e191..32d038c21 100644
--- a/dev/check-redirects.mjs
+++ b/dev/check-redirects.mjs
@@ -10,8 +10,8 @@
* - the source has no #fragment: browsers never send fragments, so such an
* entry can never match
* - the source has no earlier entry: the middleware uses the first match only
- * - neither path starts with /docs: the middleware strips that prefix from
- * requests and adds it to destinations
+ * - neither path starts with the basePath (docs.config.js): Next strips it
+ * from requests and the middleware adds it to destinations
* - the destination is a page, not another redirect
* - the destination page exists under docs/ (or is a file under public/)
* - when the destination has a #fragment, the heading exists on that page
@@ -39,11 +39,13 @@ import path from 'path';
import vm from 'vm';
import {fileURLToPath} from 'url';
import {extractHeadings, listFiles, routeFor} from './check-links.mjs';
+import config from '../docs.config.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const args = process.argv.slice(2);
const ROOT_DIR = path.resolve(flagValue('--root') ?? path.dirname(__dirname));
+const BASE_PATH = config.DOCS_BASE_PATH;
const FORMAT = flagValue('--format') ?? 'text';
const BASELINE_FILE = flagValue('--baseline');
const LINK_BASE = flagValue('--link-base')?.replace(/\/$/, '');
@@ -72,12 +74,12 @@ const PROBLEM = {
'If the redirect destination has a #fragment, it takes precedence, otherwise if the customer ' +
"clicked a link which has a #fragment, it'll be kept and tried on the destination page."
},
- docsPrefix: {
- heading: 'Source or destination starts with /docs',
+ basePathPrefix: {
+ heading: `Source or destination starts with ${BASE_PATH}`,
fix:
- 'Write paths without the /docs prefix. The site removes /docs from the requested URL before ' +
- 'matching sources, and adds it back in front of the destination, so a /docs/... source never ' +
- 'matches and a /docs/... destination lands on /docs/docs/....'
+ `Write paths without the ${BASE_PATH} prefix. The site removes ${BASE_PATH} from the requested URL before ` +
+ `matching sources, and adds it back in front of the destination, so a ${BASE_PATH}/... source never ` +
+ `matches and a ${BASE_PATH}/... destination lands on ${BASE_PATH}${BASE_PATH}/....`
},
duplicateSource: {
heading:
@@ -198,7 +200,8 @@ function findBrokenRedirects(redirects, headingsByRoute) {
const report = (redirect, problem, {detail, fix} = {}) =>
findings.push({...redirect, problem: problem.heading, detail, fix});
const withoutFragment = url => url.split('#')[0];
- const withoutDocsPrefix = url => url.replace(/^\/docs(?=\/)/, '');
+ const withoutBasePath = url =>
+ url.startsWith(`${BASE_PATH}/`) ? url.slice(BASE_PATH.length) : url;
const isRedirect = pathname =>
firstBySource.has(pathname) && !headingsByRoute.has(pathname);
@@ -220,13 +223,13 @@ function findBrokenRedirects(redirects, headingsByRoute) {
report(redirect, PROBLEM.shadowsPage);
}
if (
- source.pathname.startsWith('/docs/') ||
- redirect.destination.startsWith('/docs/')
+ source.pathname.startsWith(`${BASE_PATH}/`) ||
+ redirect.destination.startsWith(`${BASE_PATH}/`)
) {
- report(redirect, PROBLEM.docsPrefix, {
+ report(redirect, PROBLEM.basePathPrefix, {
fix: {
- source: withoutDocsPrefix(redirect.source),
- destination: withoutDocsPrefix(redirect.destination)
+ source: withoutBasePath(redirect.source),
+ destination: withoutBasePath(redirect.destination)
}
});
continue;
diff --git a/dev/verify-links-live.mjs b/dev/verify-links-live.mjs
index b39d32f4b..f2120d68e 100644
--- a/dev/verify-links-live.mjs
+++ b/dev/verify-links-live.mjs
@@ -15,20 +15,21 @@
//
// node dev/verify-links-live.mjs --site https://.vercel.app/docs [--old-site https://sourcegraph.com/docs] [--base origin/main]
//
-// Every deployment serves under /docs (basePath in next.config.js), so --site
-// includes that prefix.
+// Every deployment serves under the basePath (docs.config.js), so --site
+// includes that prefix. Both default to production.
import { execSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';
import { extractHeadings } from './check-links.mjs';
+import config from '../docs.config.js';
const args = process.argv.slice(2);
const argValue = (flag, fallback) => {
const index = args.indexOf(flag);
return index === -1 ? fallback : args[index + 1];
};
-const SITE = argValue('--site', 'https://sourcegraph.com/docs').replace(/\/$/, '');
-const OLD_SITE = argValue('--old-site', 'https://sourcegraph.com/docs').replace(/\/$/, '');
+const SITE = argValue('--site', config.DOCS_PROD_URL).replace(/\/$/, '');
+const OLD_SITE = argValue('--old-site', config.DOCS_PROD_URL).replace(/\/$/, '');
const BASE_REF = argValue('--base', 'origin/main');
const LINK = /\]\(([^)\s]+)\)|href=["']([^"']+)["']/g;
diff --git a/docs.config.js b/docs.config.js
index f5b04f4b9..51c5d04be 100644
--- a/docs.config.js
+++ b/docs.config.js
@@ -1,8 +1,15 @@
+// sourcegraph.com proxies DOCS_BASE_PATH/* to this site. Previews and local dev
+// use the same basePath so a root-relative URL that 404s in production 404s
+// there too. To move the site, change DOCS_BASE_PATH here and the load balancer
+// rule in sourcegraph/infrastructure; nothing else spells the path out.
+const DOCS_BASE_PATH = '/docs';
+const DOCS_PROD_ORIGIN = 'https://sourcegraph.com';
+
const config = {
DOCS_LATEST_VERSION: '8.0',
- // sourcegraph.com proxies /docs/* to this site. Previews and local dev use the
- // same basePath so a root-relative URL that 404s in production 404s there too.
- DOCS_BASE_PATH: '/docs'
+ DOCS_BASE_PATH,
+ DOCS_PROD_ORIGIN,
+ DOCS_PROD_URL: `${DOCS_PROD_ORIGIN}${DOCS_BASE_PATH}`
};
module.exports = config;
diff --git a/src/app/[...slug]/page.tsx b/src/app/[...slug]/page.tsx
index 095d5871c..831eab97d 100644
--- a/src/app/[...slug]/page.tsx
+++ b/src/app/[...slug]/page.tsx
@@ -35,7 +35,7 @@ export const generateMetadata = async ({params}: Props) => {
// The root layout's canonical is the landing page; without this
// override every docs page tells search engines it is a duplicate
// of https://sourcegraph.com/docs.
- alternates: {canonical: `/docs${post.url}`},
+ alternates: {canonical: withBasePath(post.url)},
openGraph: {
images: [{url: ogImageUrl, width: 1200, height: 630}]
},
diff --git a/src/app/api/versions/route.ts b/src/app/api/versions/route.ts
index 686d5c24e..b87d9c031 100644
--- a/src/app/api/versions/route.ts
+++ b/src/app/api/versions/route.ts
@@ -1,4 +1,5 @@
import {versions} from '@/data/versions';
+import config from 'docs.config';
import {NextResponse} from 'next/server';
// Next 15+ no longer caches GET handlers by default; the version list is
@@ -9,7 +10,7 @@ export function GET() {
return NextResponse.json(
versions.map((version, index) =>
index === 0
- ? {...version, url: 'https://sourcegraph.com/docs'}
+ ? {...version, url: config.DOCS_PROD_URL}
: version
),
{
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 97a20de64..3a696a774 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -12,7 +12,7 @@ import {Suspense} from 'react';
import '@/styles/tailwind.css';
export const metadata: Metadata = {
- metadataBase: new URL('https://sourcegraph.com'),
+ metadataBase: new URL(config.DOCS_PROD_ORIGIN),
title: {
template: '%s - Sourcegraph docs',
default: 'Sourcegraph docs'
@@ -24,7 +24,7 @@ export const metadata: Metadata = {
'docsearch:version': `v${config.DOCS_LATEST_VERSION}`
},
alternates: {
- canonical: '/docs'
+ canonical: config.DOCS_BASE_PATH
},
openGraph: {
images: [{url: withBasePath('/api/og/index'), width: 1200, height: 630}]
diff --git a/src/app/robots.ts b/src/app/robots.ts
index 35d3bdba1..ed87f84e1 100644
--- a/src/app/robots.ts
+++ b/src/app/robots.ts
@@ -1,4 +1,5 @@
import {MetadataRoute} from 'next';
+import config from 'docs.config';
export default async function robots(): Promise {
return {
@@ -6,6 +7,6 @@ export default async function robots(): Promise {
userAgent: '*',
allow: '/'
},
- sitemap: 'https://sourcegraph.com/docs/sitemap.xml'
+ sitemap: `${config.DOCS_PROD_URL}/sitemap.xml`
};
}
diff --git a/src/app/sitemap.ts b/src/app/sitemap.ts
index 618ceb52f..968493c84 100644
--- a/src/app/sitemap.ts
+++ b/src/app/sitemap.ts
@@ -1,12 +1,11 @@
import {MetadataRoute} from 'next';
import {allPosts} from 'contentlayer/generated';
+import config from 'docs.config';
export default async function sitemap(): Promise {
- const baseUrl = 'https://sourcegraph.com/docs';
-
const links: MetadataRoute.Sitemap = [
{
- url: baseUrl,
+ url: config.DOCS_PROD_URL,
lastModified: new Date(),
changeFrequency: 'weekly',
priority: 1.0
@@ -18,7 +17,7 @@ export default async function sitemap(): Promise {
.forEach(post => {
const priority = post.seoPriority;
links.push({
- url: `${baseUrl}${post.url}`,
+ url: `${config.DOCS_PROD_URL}${post.url}`,
lastModified: post.date ? new Date(post.date) : new Date(),
changeFrequency: 'weekly',
...(priority !== undefined && priority !== 0.5 && {priority})
diff --git a/src/components/VersionSelector.tsx b/src/components/VersionSelector.tsx
index 90b34b93c..4fcfa8cbe 100644
--- a/src/components/VersionSelector.tsx
+++ b/src/components/VersionSelector.tsx
@@ -8,13 +8,14 @@ import {
ChevronDownIcon
} from '@heroicons/react/20/solid';
import clsx from 'clsx';
+import config from 'docs.config';
import Link from 'next/link';
import {usePathname} from 'next/navigation';
import {Fragment, useEffect, useState} from 'react';
const versionsUrl =
process.env.NEXT_PUBLIC_DOCS_VERSIONS_URL ??
- 'https://sourcegraph.com/docs/api/versions';
+ `${config.DOCS_PROD_URL}/api/versions`;
function isVersion(value: unknown): value is VersionI {
if (typeof value !== 'object' || value === null) return false;
diff --git a/src/components/search/Search.tsx b/src/components/search/Search.tsx
index 4d7a3de22..b1418d17d 100644
--- a/src/components/search/Search.tsx
+++ b/src/components/search/Search.tsx
@@ -1,4 +1,5 @@
import {withBasePath} from '@/lib/utils';
+import config from 'docs.config';
import {productFilters, searchMetadata} from '../../data/search';
import {DocSearch} from './docsearch/DocSearch';
import type {DocSearchHit} from './docsearch/types';
@@ -6,14 +7,12 @@ import './docsearch/docsearch.css';
// import '@docsearch/css';
-// The Algolia crawler indexes production, so every hit URL is absolute
-// (https://sourcegraph.com/docs/...). Rewrite them to root-relative paths so
-// results stay on whichever deployment is being viewed.
-const PROD_DOCS_URL_PREFIX = 'https://sourcegraph.com/docs';
-
+// The Algolia crawler indexes production, so every hit URL is absolute.
+// Rewrite them to root-relative paths so results stay on whichever deployment
+// is being viewed.
const toLocalUrl = (url: string): string =>
- url.startsWith(PROD_DOCS_URL_PREFIX)
- ? withBasePath(url.slice(PROD_DOCS_URL_PREFIX.length))
+ url.startsWith(config.DOCS_PROD_URL)
+ ? withBasePath(url.slice(config.DOCS_PROD_URL.length))
: url;
const hitPriority = (hit: DocSearchHit): number => {
diff --git a/src/data/search.ts b/src/data/search.ts
index 2cda44b00..e50883263 100644
--- a/src/data/search.ts
+++ b/src/data/search.ts
@@ -67,7 +67,9 @@ export const curatedSearchSuggestions = [
export const searchMetadata = {
provider: 'kbar',
kbarConfig: {
- searchDocumentsPath: '/docs/search.json' // path to load documents to search
+ // Root-relative like every public/ path; contentlayer.config.ts only checks
+ // it is set before writing public/search.json.
+ searchDocumentsPath: '/search.json'
},
// For Algolia
// provider: 'algolia',
diff --git a/src/data/versions.ts b/src/data/versions.ts
index f36a7442c..db5dcc035 100644
--- a/src/data/versions.ts
+++ b/src/data/versions.ts
@@ -11,7 +11,7 @@ export const versions: VersionI[] = [
{
name: `v${config.DOCS_LATEST_VERSION}`,
label: 'latest',
- url: '/docs'
+ url: config.DOCS_BASE_PATH
},
{
name: 'v7.7',
From 04645b7b2c0dd82b90569135a6fe8a622c811bc6 Mon Sep 17 00:00:00 2001
From: Marc LeBlanc <7050295+marcleblanc2@users.noreply.github.com>
Date: Thu, 17 Sep 2026 03:56:45 -0600
Subject: [PATCH 07/11] chore: drop the kbar search index and the dead MDX
video mapping
kbar was removed in #110; the contentlayer onSuccess hook kept writing a
725 KB public/search.json that nothing fetched. src/utils/contentlayer.ts
only existed to build that index.
MDX compiles an explicit