Building and Deploying the Docsaurus Site via Vercel
Prerequisites, local setup, pushing to Bitbucket, connecting Vercel, and serving the site at corespan.ai/docs.
This document records how the Corespan documentation site was built from an empty
machine and deployed to production. It includes the prerequisites, how the dependencies were
installed locally, how the project was pushed to Bitbucket, how Bitbucket was
connected to Vercel for the build, and how the site was published at
corespan.ai/docs.
Engineering & operations reference
This is an engineering and operations reference for people who maintain or re-create the documentation deployment, not an end-user guide.
1. Prerequisites
Install and prepare the following before starting:
- Node.js 20 or later. The project declares
"engines": { "node": ">=20.0" }, and the build fails on earlier versions. Installing Node also installsnpm. - npm. The repository commits a
package-lock.json, sonpmis the package manager of record. (Some older notes showyarncommands; the lockfile is the authoritative choice — usenpm.) - Git. Required to version the project and push it to Bitbucket.
- A Bitbucket account with permission to create a repository.
- A Vercel account connected to that Bitbucket workspace.
- A code editor such as Visual Studio Code.
2. Install the dependencies on the local desktop
First, install the toolchain, then install the project packages.
-
Install Node.js and npm. Download the Node.js 20 LTS installer from nodejs.org and run it. Confirm both tools are on the path:
node --version # v20.x or later npm --version -
Install Git from git-scm.com and set the identity used for commits:
git --version git config --global user.name "Your Name" git config --global user.email "you@corespan.ai" -
Install the project packages. The Docusaurus project lives one level down, in
corespan_docs/. There is nopackage.jsonat the repository root, so installing from the root does nothing. Change into the project directory first:cd corespan_docs npm install -
Run the site locally to confirm the install. The
startandbuildscripts both compile the search Web Worker first (build:worker), so a plain Docusaurus command is not enough:npm start # dev server at http://localhost:3000/docs/ npm run build # production build into corespan_docs/build/ npm run serve # serve the production build locallyCreate a
corespan_docs/.env.localfile with the Supabase and site variables (SUPABASE_URL,SUPABASE_PUBLISHABLE_DEFAULT_KEY,DOC_SITE_URL, and the related keys) before running the dev server, because Docusaurus loads that file automatically outside production.
3. Install and configure documentation versions
Docusaurus versioning keeps a browsable snapshot of the documentation for each
released product version, while the live docs/ folder holds the in-progress
version. The configuration lives in docusaurus.config.ts, and the snapshots are
generated files committed to the repository.
How versioning is set up in this project:
- The
docs/folder is the "current" version. In thedocspreset'sversionsmap it is mapped to the development release, labeled 4.0.0 (Development), served under thenextpath (/docs/reference/next/…), and marked with anunreleasedbanner. - Released snapshots are separate directories. Each cut version lives in
versioned_docs/version-<X.Y.Z>/, its sidebar inversioned_sidebars/version-<X.Y.Z>-sidebars.json, and the list of versions to build inversions.json. lastVersion: '3.4.1'sets the default. Version 3.4.1 is what a visitor sees first, and itspath: '/'serves it at the base of the reference route (/docs/reference/…) rather than under a version segment. Older versions resolve under their number, such as/docs/reference/3.4.0/….
To cut a new version:
-
Finish editing the pages in
docs/for the release. -
Run the version command from
corespan_docs/:npm run docusaurus docs:version 3.4.1This copies
docs/intoversioned_docs/version-3.4.1/, copies the current sidebar intoversioned_sidebars/version-3.4.1-sidebars.json, and prepends"3.4.1"toversions.json. -
Update the
versionsmap indocusaurus.config.tsto set the label, path,lastVersion, and any banner for the new release and the current development version. -
Commit the generated
versioned_docs/,versioned_sidebars/, andversions.jsontogether with the configuration change.
A version directory is built only when versions.json lists it. For example,
versioned_docs/version-3.2.0/ exists on disk but is absent from versions.json,
so it is not served. Removing a version's entry from versions.json drops it from
the build without deleting its files.
4. Initialize Git and push to Bitbucket
With the project running locally, put it under version control and publish it to Bitbucket.
-
Create the repository on Bitbucket. In the Bitbucket workspace, create a new, empty repository (no README, no
.gitignore) and copy its clone URL. -
Initialize Git in the repository root — the directory that contains
corespan_docs/, notcorespan_docs/itself — so the whole project is tracked. A Docusaurus.gitignorealready excludesnode_modules/,build/, and.docusaurus/; confirm those are ignored so generated output is never committed.git init git add . git commit -m "Initial commit: Docusaurus documentation site" -
Add the Bitbucket remote and push the default branch:
git branch -M main git remote add origin https://<user>@bitbucket.org/<workspace>/<repo>.git git push -u origin mainBitbucket prompts for credentials on the first push. Use an app password, not the account password, because Bitbucket requires one for Git over HTTPS.
5. Connect the Bitbucket repository to Vercel
Vercel runs the build on every push. The Vercel project for this site is named
corespan_documentation and its production hostname is zensical-test.vercel.app.
-
Import the repository. In the Vercel dashboard, select Add New > Project, choose the Bitbucket workspace, and import the repository pushed in the previous step. Authorize Vercel to access Bitbucket if prompted.
-
Set the project root directory. Because the project lives in a subdirectory, set Root Directory to
corespan_docs. This is the single most important setting — without it, Vercel builds from the repository root, finds nopackage.json, and fails. -
Confirm the build settings. Vercel detects Docusaurus, but verify:
Setting Value Framework preset Docusaurus Install command npm installBuild command npm run buildOutput directory buildNode.js version 20.x The
npm run buildscript is deliberate because besides the Docusaurus build, it compiles the search worker and runs the post-build scripts that move the protected search index and page chunks out of the public output. Overriding the build command with a baredocusaurus buildwould ship that content unprotected. -
Add the environment variables. Under Settings > Environment Variables, add the same keys used in
.env.local—SUPABASE_URL,SUPABASE_PUBLISHABLE_DEFAULT_KEY,DOC_SITE_URL,CORESPAN_SITE_URL,AUTH_COOKIE_DOMAIN(set to.corespan.aiin production), and the chat and PDF variables — for the Production environment. Nothing is hardcoded, so a preview deployment reads whatever its own environment provides. -
Deploy. Trigger the first deployment. On success, Vercel serves the build at the production alias
projectname.vercel.app. Every later push tomainrebuilds and redeploys automatically.
6. Configure the domain and serve the site at corespan.ai/docs
The site is a zone. The public path corespan.ai/docs is not a Vercel custom
domain on this project directly; it is produced by the main website's Next.js
application rewriting /docs/* to this project's Vercel alias, combined with the
site's own baseUrl.
-
Keep
baseUrlset to/docs/indocusaurus.config.ts. Docusaurus usesbaseUrlonly to prefix the URLs it writes into the HTML, it still writes its files flat. The outer/docssegment is the zone and the inner segment is the documentation plugin'srouteBasePath, so a page resolves to/docs/reference/<version>/…. -
Add the rewrite in the main site. In the
frontendrepository'snext.config.ts, a rewrite points/docs/*at this project's Vercel production alias and strips the/docsprefix before the request arrives, because Docusaurus already prefixes its internal links withbaseUrl. This rewrite is what makescorespan.ai/docsresolve to the deployed documentation. -
Attach the custom domain in Vercel (optional alias). In Settings > Domains on the
corespan_documentationproject, adddocs.corespan.ai. That hostname resolves but then301-redirects inward tocorespan.ai/docs, so the canonical public URL stays under the main domain. -
Verify the published site. Because the client-side auth guard redirects before a browser can show the page source, verify with
curl, not a browser:curl -s https://www.corespan.ai/docs | wc -cRoughly 1.5 KB is the empty, signed-out shell and is correct. After a deploy, watch the response
etagchange rather than the byte count, because the edge serves the previous copy for up to a minute.
Related
- Authentication on Docusaurus — how the deployed site gates access once it is live.
- Generating and Publishing API Documentation — generating and publishing the API reference documentation.
Static Site Generator (Docusaurus)
Engineering references for building, deploying, authenticating, and documenting the Corespan Docusaurus site.
Generating and Publishing API Documentation
Installing the OpenAPI plugin, configuring docusaurus.config.ts, adding the Postman-exported spec, generating MDX pages, and matching the API version to 4.0.0.