Skip to content

MkDocs + Vercel

I wasn't satisfied with any of the existing guides for deploying an MkDocs site to Vercel, so I wrote my own.

This method uses GitHub Actions to build and deploy your site via the Vercel CLI.

Prerequisites

Configuring Your Project

First and foremost, you'll need to install the Vercel CLI on your own machine.

npm i -g vercel

yarn global add vercel

pnpm i -g vercel

Connect it to your Vercel account:

vercel login

Then switch into your project's directory and link it to Vercel:

vercel link

After following the interactive prompts, a .vercel folder will appear in your project's directory. Inside that folder is a project.json file with a projectId property and an orgId property. Add the values of these properties as secrets in your project's GitHub repository under the names VERCEL_PROJECT_ID and VERCEL_ORG_ID, respectively.

You can do this on GitHub.com or with the GitHub CLI:

gh secret set VERCEL_PROJECT_ID
gh secret set VERCEL_ORG_ID # (1)!
  1. You'll be interactively prompted for the respective secret after running each command.

Using vercel.json

You can use a vercel.json file in your project by simply dropping it into the docs folder. MkDocs will automatically include it in the build output.

Getting a Token

You'll need to generate a Vercel token so the Vercel CLI can access your account from within GitHub Actions. Head over to your Vercel account settings, choose a name, appropriate scope, and expiration date for your token, and click Create. Copy the token and set it as a repository secret under the name VERCEL_TOKEN.

Writing the Workflow

Finally, you need to write a GitHub Actions workflow that builds your documentation and deploys it to Vercel. You have practically infinite flexibility in how this workflow looks, but it should probably contain the following at a minimum:

# .github/workflows/docs.yml

on:
  push:
    paths:
      - docs/**
      - mkdocs.yml

  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Set Up Python
        uses: actions/setup-python@v4

      # Install MkDocs, other dependencies, and do whatever else you need to do, then...

      - name: Build
        run: mkdocs build

      - name: Upload Artifact
        uses: actions/upload-artifact@v3
        with:
          name: site
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Download Artifact
        uses: actions/download-artifact@v3
        with:
          name: site
          path: site

      - name: Deploy to Vercel
        uses: npx vercel --yes --cwd site --token ${{ secrets.VERCEL_TOKEN }} # (1)!
        env:
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

  1. To create a production deployment, tack on the --prod flag:

    npx vercel --yes --cwd site --token ${{ secrets.VERCEL_TOKEN }} --prod

    To emulate Vercel's branch-dependent creation of preview and production deployments, you can do something like this (replacing main with your production branch if necessary):

    npx vercel --yes --cwd site --token ${{ secrets.VERCEL_TOKEN }} ${{ github.ref == 'refs/heads/main' && '--prod'||'' }}

That's it. Your site will now be deployed to Vercel on every push that changes the contents of the docs folder, mkdocs.yml, or anything else you choose to specify in on.push.paths.

You can check out a fully-functioning example workflow at this website's repository.