Skip to content

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

Open
marcleblanc2 wants to merge 7 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 7 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

  • Prod serves the site at sourcegraph.com/docs

  • Preview and dev deployments 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 worked in preview but broke in prod

Change

  • This PR creates a consistent pattern:

    • There is now exactly one (1) config for DOCS_PROD_ORIGIN, in docs.config.js, set to https://sourcegraph.com
    • There is now exactly one (1) config for DOCS_BASE_PATH, in docs.config.js, set to /docs
    • Standardized paths using withBasePath(url) from src/lib/utils.ts

  • Every deployment is now served under DOCS_BASE_PATH

  • / redirects to DOCS_BASE_PATH, so preview URLs and localhost:3000 land on the site automagically

  • /v/<latest>/x redirects to /DOCS_BASE_PATH/x instead of prod, so previews can be tested end to end

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

  • Updated dev tooling and docs to match

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.

1 Skipped Deployment
Project Deployment Actions Updated
sourcegraph-docs Ignored Ignored Preview Sep 18, 2026 9:34pm 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
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
Merged
@marcleblanc2
marcleblanc2 force-pushed the marc/fix/mark-svg-base-path branch from 87b9d78 to 800c7c6 Compare September 18, 2026 04:17
@marcleblanc2
marcleblanc2 force-pushed the marc/fix/mark-svg-base-path branch from 800c7c6 to 6b9f3cb Compare September 18, 2026 05:03
This was referenced Sep 18, 2026
Draft
Open
enriquegh
enriquegh approved these changes Sep 18, 2026
View reviewed changes

@enriquegh enriquegh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! Do we need to add any of this to the old versions of our docs (e.g. 7.7.sourcegraph.com, etc)?

That shouldn't block though so approving

marcleblanc2 and others added 3 commits September 18, 2026 15:22
@marcleblanc2
fix: prefix basePath on root-relative <img> src
4762a8c 
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
d184a92 
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
a195f4a 
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 and others added 4 commits September 18, 2026 15:22
@marcleblanc2 @ampagent
site: one DOCS_BASE_PATH constant; drop NEXT_PUBLIC_DOCS_BASE_PATH
93f2e11 
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
852d743 
/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
98bf1d9 
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 @ampagent
cspell: allow automagically
dcdddd0 
Amp-Thread-ID: https://ampcode.com/threads/T-01a0b664-4b80-751d-a17b-39ac6eba9e2d
Co-authored-by: Amp <amp@ampcode.com>
@marcleblanc2
marcleblanc2 force-pushed the marc/fix/mark-svg-base-path branch from 6b9f3cb to dcdddd0 Compare September 18, 2026 21:23
@marcleblanc2

marcleblanc2 commented Sep 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Do we need to add any of this to the old versions of our docs (e.g. 7.7.sourcegraph.com, etc)?

@enriquegh Amp's response below, and I'm trying to make heads or tails of it.

Do we have customers or staff who flip between different versions of the site?

  • Not for old versions, but future versions will include this change
  • The versioned sites (7.7.sourcegraph.com etc.) are frozen Vercel deployments served at the root of their own subdomain, with no basePath, so root-relative URLs already resolve there (https://7.7.sourcegraph.com/sourcegraph-mark.svg is a 200 today)
  • The bugs only show up when the site is served under /docs
  • Applying this PR to an old version would move it to <old-version>.sourcegraph.com/docs/..., breaking existing links, and requiring updating the /v/<version>/* redirects

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

Reviewers

@enriquegh enriquegh enriquegh approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@marcleblanc2 @enriquegh