skip to content
[WH LIAO]
Table of Contents

This article provides a new approach to deploying Material for MkDocs on Vercel using the latest vercel.json configuration and UV package manager. This method can avoid errors related to Vercel’s updated deployment policy (now mandatory to use Node.js 22.x).

Project Structure

Here’s the example file structure for MkDocs project:

mkdocs-project/
├── docs/                     # MkDocs documentation source
│   ├── blog/
│   │   ├── index.md
│   │   └── posts/
│   ├── images/
│   ├── javascripts/
│   ├── stylesheets/
│   └── index.md
├── overrides/               # Custom MkDocs theme overrides
├── mkdocs.yml               # MkDocs configuration
├── pyproject.toml           # Python project configuration with UV
├── vercel.json              # Vercel deployment configuration
├── uv.lock                  # UV lock file (auto-generated)
└── README.md

Configuration Files

Python Dependencies with pyproject.toml

UV uses pyproject.toml to manage Python dependencies, providing faster installation and better dependency resolution compared to traditional requirements.txt:

pyproject.toml
[project]
name = "mkdocs-blog"
version = "1.0.0"
description = "Personal blog built with MkDocs"
readme = "README.md"
requires-python = ">=3.9"
dependencies = [  # add mkdocs related packages here
    "mkdocs-material",
    "mkdocs-glightbox",
    "mkdocs"
]

UV resolves dependencies from pyproject.toml and creates/updates the lock file uv.lock automatically. More importantly, UV can add a venv for each project, which is convenient for managing dependencies.

Vercel JSON Configuration

The vercel.json file provides a clean and simple deployment configuration:

vercel.json
{
  "installCommand": "pip3 install uv", // (1)
  "buildCommand": "uv sync && uv run mkdocs build -d public --clean",
  "outputDirectory": "public"
}
  1. Must use pip3 specified in Vercel.

Vercel has a built-in Python 3.12 environment, so we can use pip3 to install uv first, then use uv sync to install other dependencies form pyproject.toml. After that, using uv run mkdocs build -d public --clean to build the static site to the public directory with a clean build and tell Vercel to serve files from the public directory.

Deployment Process

1. Push Repository to GitHub

Commit and push your project to a GitHub repository:

Terminal window
git add .
git commit -m "Add Vercel JSON configuration with UV"
git push origin main

2. Connect to Vercel

  1. Go to Vercel Dashboard
  2. Click “New Project”
  3. Import your GitHub repository
  4. Vercel will automatically detect the vercel.json configuration
  5. Click “Deploy”

3. Automatic Deployment

Vercel will execute environment setup and build commands automatically, then serve the generated public directory.

Local Test

Before deploying, you can test the build process locally:

Terminal window
pip install uv
uv sync
uv run mkdocs serve

Other methods

Besides building the site on Vercel, you can also refer to MkDocs + Vercel to build the site with Github Actions, then serve the generated site with Vercel.

Backlinks