Deploying MkDocs with a Virtual Environment to GitHub Pages
Setting up a virtual environment for your MkDocs project is best practice for keeping your dependencies isolated and your deployment clean. This guide walks you through creating a venv, installing dependencies, and deploying your documentation site to GitHub Pages.
Why Use a Virtual Environment?
A virtual environment lets you keep all your Python packages and project dependencies isolated from your system Python installation. This ensures that your MkDocs build is reproducible and avoids version conflicts.
Create a Virtual Environment
First, navigate to your project folder and run:
cd E:\Blog\personal-website
python -m venv venv
This creates a venv folder in your project.
Activate it with:
# On Windows
.\venv\Scripts\Activate
# On macOS/Linux
source venv/bin/activate
You’ll see (venv) appear in your terminal — you’re working inside your isolated environment!
Install MkDocs and Plugins
Inside the venv, install MkDocs, Material for MkDocs, and any plugins you need:
pip install mkdocs mkdocs-material mkdocs-ultralytics-plugin mkdocstrings mkdocs-open-in-new-tab
Optionally, freeze your exact versions:
pip freeze > requirements.txt
This lets you reinstall everything later with:
pip install -r requirements.txt
Build and Preview Your Site Locally
Before deploying, always check that your site builds correctly:
mkdocs build
mkdocs serve
Open http://127.0.0.1:8000 and confirm your site looks as expected.
Push Your Work to GitHub
Make sure your mkdocs.yml and docs/ content are tracked in Git:
git add .
git commit -m "Initial site build with venv"
git push origin main
🔑 Tip: Never push the venv folder — always add venv/ to your .gitignore.
Deploy to GitHub Pages
Deploy directly with:
mkdocs gh-deploy --clean
This:
- Builds your site.
- Pushes the site/ output to a gh-pages branch.
- Publishes to https://<your-username>.github.io/<repo>.
Keep It Clean: .gitignore
Your .gitignore should always exclude:
venv/
__pycache__/
site/
*.pyc
This keeps your repo clean and avoids accidentally pushing build files or Python cache files.
Updating Your Site
When you make edits:
1. Activate the venv:
.\venv\Scripts\Activate
mkdocs build
mkdocs gh-deploy --clean
Conclusion
Using a virtual environment ensures your MkDocs project remains isolated and reproducible. Combined with GitHub Pages, you have a simple, robust, and fully automated way to publish your site to the world.
Happy documenting! 🚀
