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. In the Overview tab, select Create a New Project.
  2. 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, Cloudflare shows you a list of the repositories you can use.
  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.
    • 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 Name, and your GitHub personal access token as the Value. Select Add. Vercel automatically encrypts the value.
  5. Select Deploy. Vercel builds your site. When it is ready, you can view it at the autogenerated preview link, available on the site Overview page.

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