🚀 Deploying MkDocs on GitHub Pages with DevContainers
If you're looking for a simple yet powerful way to create and deploy documentation, MkDocs with GitHub Pages is an excellent choice. In this guide, we'll walk through setting up MkDocs, using DevContainers for a consistent development environment, and automating deployment with GitHub Actions.
1️⃣ Setting Up Your GitHub Repository
First, create a new GitHub repository to host your MkDocs site:
- Go to GitHub → Create a New Repository
- Configure the repository:
-
Name:
mkdocs-demo
- Visibility: Public (recommended for GitHub Pages)
- Initialize with README: ✅ (checked)
-
Name:
- Click Create repository.
Once created, clone the repository locally:
git clone https://github.com/YOUR_USERNAME/mkdocs-demo.git
cd mkdocs-demo
Replace YOUR_USERNAME
with your actual GitHub username.
2️⃣ Using DevContainers for Development
A DevContainer provides a consistent development setup using Docker. Follow these steps to use it:
- Ensure Docker and VS Code's Dev Containers extension are installed.
- Open the repository in VS Code.
- Press
Ctrl+Shift+P
, then select "Reopen in Container". - Wait for the container to build and install dependencies automatically.
3️⃣ Installing MkDocs and Plugins
If you are not using DevContainers, manually install the required dependencies:
python3 -m pip install -r requirements.txt
Ensure requirements.txt
contains:
mkdocs
mkdocs-material
pymdown-extensions
mkdocs-minify-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-include-dir-to-nav
mkdocs-git-committers-plugin-2
mkdocs-redirects
mkdocs-awesome-pages-plugin
mkdocs-nav-weight
4️⃣ Creating and Structuring Documentation
Run:
python3 -m mkdocs new .
This creates a docs/
directory with a default index.md
file. You can now add content:
mkdir -p docs/guides docs/tutorials docs/javascripts docs/stylesheets
echo "# Welcome to MkDocs" > docs/index.md
echo "Intro to MkDocs." > docs/guides/intro.md
echo "Advanced MkDocs usage." > docs/guides/advanced.md
echo "Setup guide." > docs/tutorials/setup.md
echo "Deployment guide." > docs/tutorials/deployment.md
5️⃣ Configuring mkdocs.yml
Edit mkdocs.yml
to customize your site:
site_name: mkdocs-demo
site_url: https://YOUR_USERNAME.github.io/mkdocs-demo/
site_author: YOUR_NAME
repo_name: YOUR_USERNAME/mkdocs-demo
repo_url: https://github.com/YOUR_USERNAME/mkdocs-demo
theme:
name: material
palette:
primary: 'indigo'
accent: 'indigo'
features:
- content.code.copy
- content.code.annotate
nav:
- Home: index.md
- Guides:
- Introduction: guides/intro.md
- Advanced Topics: guides/advanced.md
- Tutorials:
- Setup Guide: tutorials/setup.md
- Deployment Guide: tutorials/deployment.md
Replace YOUR_USERNAME
and YOUR_NAME
with actual values.
6️⃣ Previewing the Site Locally
To check your site before deployment, run:
python3 -m mkdocs serve --dev-addr=0.0.0.0:8000
Then open http://127.0.0.1:8000/
in your browser.
7️⃣ Automating Deployment with GitHub Actions
To automate deployment, create a workflow file at .github/workflows/ci.yml
:
name: Deploy MkDocs
on:
push:
branches:
- main
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: 3.x
- run: pip install -r requirements.txt
- run: mkdocs gh-deploy --force
This workflow:
- Runs when pushing to
main
. - Installs dependencies.
- Deploys the MkDocs site to GitHub Pages.
8️⃣ Enabling GitHub Pages
To finalize the deployment:
- Go to your repository Settings.
- Scroll to Pages.
- Under Build and Deployment, select GitHub Actions.
- If needed, set
gh-pages
as the deployment branch.
Your site will be available at:
https://YOUR_USERNAME.github.io/mkdocs-demo/
🔟 Deploying Updates
To deploy changes, commit and push updates:
git add --all
git commit -m "Update documentation"
git push origin main
GitHub Actions will automatically build and deploy the site.
🎉 Your MkDocs site is now live! 🚀
A working example of this setup can be found at: GitHub - jdevto/mkdocs-demo. The deployed site is available at jdevto.github.io/mkdocs-demo. This repository also includes .devcontainer
configurations for easy local development.
Top comments (0)