Deploying with Vercel

Vercel official documentation

Config is versioned at vercel.json in the repo root directory

{"buildCommand":"python3 -m pdm run mkdocs build","outputDirectory":"site","installCommand":"python3 --version && python3 -m pip install pdm 'urllib3<2' && python3 -m pdm install --no-default -dG docs -v && python3 -m pdm run mkdocs"}

Config to build a `mkdocs` site¶

The Vercel deployment config is stored in vercel.json at the project root.

It sets the following on your docs site deployment:

Build command mkdocs build but ensured to be run through PDM
Output directory site
Install command The command below (but as a one-liner):

python3 --version && \
python3 -m pip install pdm 'urllib3<2' && \
python3 -m pdm install --no-default -dG docs -v && \
python3 -m pdm run mkdocs

Vercel and urllib3<2

The urllib3 dep is pinned because Vercel "runners" are based on Amazon Linux 2, a close relative of RHEL which shipped with OpenSSL v1.0.2, whereas urllib3 v2 imposes a minimum of OpenSSL v1.1.1.

The install command will:

Print out the Python version (3.9.8 at the time of writing),
Install PDM (and v1.x of urllib3; see note in sidebar),
Install the docs dependency group with the -G flag (it's a "dev dependency" so you also use -d)
Run mkdocs to print out the usage (as confirmation that it was successfully installed)

GitHub integration¶

Privacy¶

If your repo is private, Vercel will require users to login to determine access.

This repo is public (here) so the website is too (both the default branch here as well as preview deployments for commits in PRs).

CI bot¶

To install a Vercel CI bot that will comment on all of your PRs, install the Vercel GitHub App on your account.

It's shown in a Deployments panel to the right of the repo and at /deployments.