Skip to content

meta

  • in meta
  • 3 min read

Deploying Material for MkDocs on Vercel (and the Python entrypoint rabbit hole)

I wanted this site on Vercel as well as GitHub Pages. MkDocs Material is just static HTML once it’s built—how hard could it be?

Pretty hard, as it turned out.

The error that made no sense at first

Every deploy died with something like:

[PYTHON_ENTRYPOINT_NOT_FOUND] No python entrypoint found.
Set "tool.vercel.entrypoint" in pyproject.toml or define an entrypoint in one of:
app.py, index.py, server.py, main.py, ...

I don’t have a Python API. I have Markdown, a mkdocs.yml, and a blog plugin. There is no app.py, and there never should be.

That’s the clue: Vercel wasn’t treating my repo as a static site. It was treating it as a Python application that was supposed to boot a web server on every request.

Why Vercel thought I was building an app

On newer Vercel tooling, seeing Python-ish project files—especially something like requirements.txt at the repo root—can push the platform down a “run this as Python” path. MkDocs uses Python at build time, but the product is a folder of HTML, CSS, and JS in site/.

I tried the obvious fixes:

  • Setting "framework": null in vercel.json
  • Moving dependencies to requirements-mkdocs.txt so the root didn’t scream “Python project”
  • A package.json script that ran pip install and mkdocs build, with Vercel pointed at a public/ output directory

Some of that got closer. None of it felt reliable, and I kept worrying the next Vercel update would break it again. I was fighting the platform instead of using it the way MkDocs actually works.

The approach that finally worked

The guide that clicked for me was MkDocs + Vercel by celsiusnarhwal. The idea is simple:

  1. Build on GitHub Actions (or anywhere you control): pip install, then mkdocs build.
  2. Deploy the site/ folder with the Vercel CLI—upload static files, don’t ask Vercel to run MkDocs or Python.

So the workflow is: checkout → install requirements-mkdocs.txt → mkdocs build --strict → npx vercel --prod with working-directory: site.

That matches how I already think about the project: Python is a build tool, not the hosting runtime.

Trailing slashes (easy to miss)

On GitHub Pages, MkDocs-style links often “just work.” On Vercel, relative links can break if URLs don’t use trailing slashes the way MkDocs expects. The guide recommends a tiny docs/vercel.json:

{
  "trailingSlash": true
}

MkDocs copies it into site/ when you build, so the deployed bundle carries the right behavior.

Stop Vercel from building on every git push

If the Vercel Git integration is still trying to build the repo on each push, you can get the old Python entrypoint error even after you fix CI. I either disconnect Git in the Vercel project or set Ignored Build Step to exit 0 so only the GitHub Action deploys via the CLI.

Secrets you need once

After vercel link locally, GitHub Actions needs:

  • VERCEL_TOKEN (from your Vercel account tokens)
  • VERCEL_ORG_ID and VERCEL_PROJECT_ID (from .vercel/project.json)

Those are boring copy-paste steps, but you only do them once.

What I’d tell past-me

  • Don’t deploy MkDocs on Vercel’s Python runtime unless you’re actually shipping a Python web app.
  • Build static files in CI, then vercel --prod from site/.
  • Read MkDocs + Vercel before inventing another vercel.json hack.

GitHub Pages still deploys this repo from mkdocs gh-deploy on main. Vercel is a second host for the same built site—and now it behaves.

If you’re stuck on PYTHON_ENTRYPOINT_NOT_FOUND with MkDocs, you’re probably not missing an app.py. You’re probably deploying the wrong kind of project.