Vercel Steps for MkDocs¶

You can definitely use Vercel to deploy an MkDocs site! Here’s a step-by-step guide on how to do that:

Step 1: Install MkDocs¶

If you haven't already, install MkDocs on your local machine:

pip install mkdocs

Step 2: Create Your MkDocs Project¶

Create a new MkDocs project:

mkdocs new my-project
cd my-project

Step 3: Build Your Docs¶

Build your MkDocs site to generate the static files:

mkdocs build

This will create a site directory containing your static files.

Step 4: Set Up a Git Repository¶

Initialize a Git repository in your MkDocs project:

git init
git add .
git commit -m "Initial commit"

Step 5: Push to a Git Hosting Service¶

Push your repository to a Git service like GitHub, GitLab, or Bitbucket.

git remote add origin <your-repo-url>
git push -u origin master

vercel login

# this will ask for one-time device code to login
https://vercel.com/oauth/device?user_code=PBVQ-CVDN

# after logging in, you will get a token

Step 5.2: deploy using vercel-cli¶

vercel deploy

# or alternative
vercel

this will ask for a project name and a git repository to deploy to

Step 5.3: deploy with prod flag¶

vercel deploy --prod

Go to Vercel.com and sign up or log in.

Step 7: Create a New Project¶

Click on the "New Project" button.
Import the repository you just created.
Vercel will automatically detect it as a static site.

Step 8: Configure Build Settings¶

In the Vercel project settings, set the following:

Framework Preset: Select "Other" if MkDocs is not listed.
Build Command: Set it to mkdocs build.
Output Directory: Set it to site.

Step 9: Deploy¶

Click on the "Deploy" button. Vercel will build and deploy your MkDocs site.

Step 10: View Your Site¶

Once the deployment is complete, you will receive a URL where your MkDocs site is hosted.

Additional Options¶

If you encounter issues, you may consider using alternative hosting services that support static sites, such as GitHub Pages or Netlify, which can also work well with MkDocs.

Conclusion¶

Using Vercel is a great option for deploying MkDocs! Follow the steps above, and you should have your documentation site up and running in no time.

common issues deploying mkdocs to vercel¶

Yes, there are some common issues you might encounter when deploying MkDocs to Vercel. Here are a few along with their potential solutions:

1. Build Command Errors¶

Issue: The build command (mkdocs build) may fail if MkDocs is not installed or not recognized.
Solution: Ensure that your project includes a requirements.txt file with mkdocs listed. Vercel needs to install the required dependencies.

2. Missing Configuration Files¶

Issue: If your mkdocs.yml configuration file is missing or incorrectly configured, the build will fail.
Solution: Double-check that your mkdocs.yml file is present and properly configured.

3. Incorrect Output Directory¶

Issue: The output directory might be set incorrectly, causing Vercel to not find the built files.
Solution: Ensure the output directory is set to site in the Vercel project settings.

4. Static Files Not Served¶

Issue: Sometimes, static files like images or CSS may not load properly.
Solution: Verify that all paths in your MkDocs configuration are correct and that the files exist in the site directory.

5. Caching Issues¶

Issue: If you update your site and the changes don't appear, it might be a caching issue.
Solution: Clear your cache in the browser or try a hard refresh. You can also trigger a new deployment in Vercel.

6. Environment Variables¶

Issue: If your MkDocs site relies on environment variables (e.g., for API keys), they must be configured in Vercel.
Solution: Set these variables in your Vercel project settings under the "Environment Variables" section.

7. Local vs. Production Discrepancies¶

Issue: Your site may work locally but fail in production due to differences in environments.
Solution: Test your build locally using mkdocs build before deploying. Use the same settings and configurations that you have in Vercel.

8. Version Compatibility¶

Issue: There may be compatibility issues between MkDocs and the version of Python or dependencies installed in Vercel.
Solution: Specify the version of MkDocs and any plugins in your requirements.txt to ensure compatibility.

By keeping these common issues in mind, you can troubleshoot and resolve problems more effectively when deploying your MkDocs site to Vercel.

Workflow using Vercel-CLI¶

plan what you want to document and how you want to organize into pages, sections, etc.
update the appropriate markdown files
if needed update the mkdocs.yml file
build and run the site locally to see if it looks good
if needed make changes to the markdown files and repeat steps 2-4
when satisfied, commit the changes
push the changes to the remote repository
deploy to vercel

mkdocs build --clean
mkdocs serve

git status
git add .
git commit -m "updated docs"
git push

# vercel login.. do per-session device login
vercel login
vercel deploy

# vercel deploy with --prod flag to deploy to production
vercel deploy --prod