Skip to content

Vercel

Vercel offers hosting for static sites (as well as a range of Jamstack services, including an integrations marketplace). You can connect your git repo (GitHub, GitLab, or Bitbucket) to set up automated deploys, including preview builds on pull request.

This post walks through deploying an MkDocs site with the Material theme.

There are some differences between deploying a site with the free Material theme, and one using Material Insiders (accessible to sponsors). This guide covers both.

Prerequisites

I've assumed you:

  • Have an MkDocs site using the Material theme
  • Are using GitHub as your remote repo (but the process should be very similar for GitLab or Bitbucket)
  • Have a Vercel account
  • If you are using Insiders, you have set up a personal access token.

Site setup

If you are using the free theme, add requirements.txt: 

1
mkdocs-material==<YOUR_MATERIAL_VERSION>

You don't need to add a runtime.txt or Pipfile. Vercel default to Python 3.9.

Deployment

  1. You need to import a git repository. If this is your first time using Vercel, go through the process to link you GitHub account. Make sure you allow access to the repo you want to deploy. Once GitHub is connected, Vercel shows you a list of the repositories you can use.
  2. On the Overview tab, select Import to import a project.
  3. Choose the repository you want to deploy.
  4. On the Configure Project screen, enter the build settings:
    • Check the Project name is correct, and that Other is selected in Framework preset.
    • The Root directory defaults to the root of the GitHub project. If you are using a monorepo, change this to the MkDocs project directory.
    • In Build and Output Settings:
      • For the Build command, enter mkdocs build.
      • Enter site (or the value of site_dir if your site uses a custom output directory name) as the Output directory.
      • For the Install command, the value varies depending on whether you're using Insiders or not. Free theme: 
        1
        pip install -r requirements.txt
        Insiders theme: 
        1
        pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
    • If using Insiders, select Environment Variables. Enter GH_TOKEN as the Key, and your GitHub personal access token as the Value. Select Add. Vercel automatically encrypts the value.
  5. Select Deploy. Vercel builds your site. This first deploy will fail, because the default build image doesn't currently (22 April 2024) support Python.
  6. Change the Vercel build image:
    1. Go to the project Settings tab.
    2. Scroll down to Node.js Version.
    3. Change the version to 18.x.
    4. Select Save.
  7. Redeploy:
    1. Go to the Deployments tab.
    2. Select the menu on the failed deployment/
    3. Select Redeploy.

For information on next steps, including adding a custom domain, refer to the documentation.