Skip to content

Serve site at a consistent, configurable basePath, for all deployments - #1977

Open
marcleblanc2 wants to merge 6 commits into
mainfrom
marc/fix/mark-svg-base-path
Open

Serve site at a consistent, configurable basePath, for all deployments#1977
marcleblanc2 wants to merge 6 commits into
mainfrom
marc/fix/mark-svg-base-path

Conversation

@marcleblanc2

@marcleblanc2 marcleblanc2 commented Sep 17, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Problem

  • The doc site has moved a few times over the years, and will move again in the coming months

  • The whiplash of these moves has resulted in a hot mess of adaptations

  • This PR sets a consistent pattern:

    • There is now exactly one (1) config for DOCS_PROD_ORIGIN
    • There is now exactly one (1) config for DOCS_BASE_PATH

  • The many different adaptations to decipher these have been centralized on these configs

  • Production serves the site at sourcegraph.com/docs

  • Previews and local dev have served it at either / or /docs at different times in history, most recently /

  • Root-relative URLs which Next.js does not prefix (<img src>, <a href>, fetch()) therefore only broke in production

Change

  • Serve every deployment under /docs

  • / redirects to /docs in dev / preview, so preview URLs and localhost:3000 still land on the site

  • Fix the broken images with withBasePath(url) in src/lib/utils.ts

  • Declare the basePath once, as DOCS_BASE_PATH in docs.config.js, replacing nine process.env.NEXT_PUBLIC_DOCS_BASE_PATH copies and a hardcoded /docs in src/proxy.ts

  • Declare the production origin once, as DOCS_PROD_ORIGIN in docs.config.js; sitemap.ts, robots.ts, layout.tsx metadata, api/versions, Search.tsx, and the dev/check-*.mjs scripts and preview-links.yml workflow all read docs.config.js instead of spelling https://sourcegraph.com/docs themselves

  • /v/<latest>/x redirects to the current deployment's /docs/x instead of production, so previews can be tested end to end

  • Update dev tooling and docs that assumed previews had no basePath

Verification

  • tsc and eslint clean
  • Against next dev:
Request Result
/ 307 → /docs
/docs/self-hosted/deploy 200, every <img src> starts with /docs/
/docs/self-hosted/deploy.md 200
/docs/v/6.0/cody 307 → https://6.0.sourcegraph.com/cody
/docs/v/7.7/cody 307 → <same host>/docs/cody
/docs/integration/img/disable_extension.png 307 → /docs/integration/img/disable-extension.png

On main, the same local setup renders src="/sourcegraph-mark.svg" and it 404s: this bug would have been caught on a preview.

@vercel

vercel Bot commented Sep 17, 2026 •
edited
Loading

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
sourcegraph-docs Ready Ready Preview Sep 17, 2026 9:52am UTC

Request Review

@github-actions

github-actions Bot commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

Open the Diff Tour for this PR in Sourcegraph

@github-actions

This comment has been minimized.

Sign in to view
@marcleblanc2
marcleblanc2 force-pushed the marc/fix/mark-svg-base-path branch from e1678da to 43372c6 Compare September 17, 2026 02:32
@marcleblanc2
marcleblanc2 force-pushed the marc/fix/mark-svg-base-path branch from f3ed48d to 0e71382 Compare September 17, 2026 08:46
@marcleblanc2 marcleblanc2 changed the title fix: prefix basePath on root-relative <img> src site: serve every deployment under /docs; prefix basePath on <img> src Sep 17, 2026
@marcleblanc2 marcleblanc2 changed the title site: serve every deployment under /docs; prefix basePath on <img> src dev: serve site at /docs for all deployment types Sep 17, 2026
@marcleblanc2 marcleblanc2 changed the title dev: serve site at /docs for all deployment types Serve every deployment under /docs Sep 17, 2026
@marcleblanc2 marcleblanc2 changed the title Serve every deployment under /docs Serve site at a consistent, configurable basePath, for all deployments Sep 17, 2026
@marcleblanc2
marcleblanc2 marked this pull request as ready for review September 17, 2026 09:49
marcleblanc2 and others added 6 commits September 17, 2026 03:50
@marcleblanc2
fix: prefix basePath on root-relative <img> src
ea2a7a4 
Production serves under /docs. next/link adds the prefix, <img> and
next/image do not, so /sourcegraph-mark.svg in the mobile nav and the
LinkCards/ProductCards icons, plus a couple of root-relative markdown
images, 404 on sourcegraph.com.
@marcleblanc2 @ampagent
cspell: allow hrefs
4c38eb7 
Amp-Thread-ID: https://ampcode.com/threads/T-01a0ae6a-1645-702a-a5ed-92f8b9bce33b
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2 @ampagent
site: serve every deployment under /docs
b5c5ac1 
Previews and local dev served at / while production served at /docs, so
a root-relative <img src> 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@ampcode.com>
@marcleblanc2 @ampagent
site: one DOCS_BASE_PATH constant; drop NEXT_PUBLIC_DOCS_BASE_PATH
cb69834 
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 <amp@ampcode.com>
@marcleblanc2 @ampagent
proxy: keep latest-version redirects on the current deployment
4251953 
/v/<latest>/x and /@<latest>/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 <amp@ampcode.com>
@marcleblanc2 @ampagent
site: derive every /docs and production URL from docs.config.js
87b9d78 
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@ampcode.com>
@marcleblanc2
marcleblanc2 force-pushed the marc/fix/mark-svg-base-path branch from bead7e1 to 87b9d78 Compare September 17, 2026 09:50
This was referenced Sep 17, 2026
Open
Draft
@marcleblanc2

marcleblanc2 commented Sep 17, 2026

Copy link
Copy Markdown
Contributor Author

From the docs site audit (crawl of all 502 pages).

The crawl confirms the three broken-image sources this PR fixes (/sourcegraph-mark.svg via MobileNavigation.tsx and the LinkCard imgSrc on 67 pages, /aws-ami-marketplace.png, /postgres_collation_affected_customers.png). Two related findings it does not cover:

  1. docs/integration/gitlab.mdx:29 references img/gitlab-code-intel.gif. Nothing serves docs/**/img (curl https://sourcegraph.com/docs/integration/img/disable-extension.png → 404), and it is the only MDX reference into that folder; the other ~50 files in docs/integration/img/ are orphaned. Moving the gif into public/ would conflict with this PR, so it may be easiest to fold in here.
  2. The canonical: this PR makes it config.DOCS_BASE_PATH (still site-wide), so every page keeps telling search engines it is a duplicate of /docs. Per-page canonical is in fix/seo: Emit a per-page canonical URL #2001; expect a trivial conflict on layout.tsx if both land.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@enriquegh enriquegh Awaiting requested review from enriquegh

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@marcleblanc2