DEV Community

John Ajera
John Ajera

Posted on

Deploying MkDocs on GitHub Pages with DevContainers

#mkdocs #github #pages #cicd

🚀 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:

  1. Go to GitHub → Create a New Repository
  2. Configure the repository:
    • Name: mkdocs-demo
    • Visibility: Public (recommended for GitHub Pages)
    • Initialize with README: ✅ (checked)
  3. Click Create repository.

Once created, clone the repository locally:

git clone https://github.com/YOUR_USERNAME/mkdocs-demo.git cd mkdocs-demo
Enter fullscreen mode Exit fullscreen mode

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:

  1. Ensure Docker and VS Code's Dev Containers extension are installed.
  2. Open the repository in VS Code.
  3. Press Ctrl+Shift+P, then select "Reopen in Container".
  4. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

4️⃣ Creating and Structuring Documentation

Run:

python3 -m mkdocs new .
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

This workflow:

  • Runs when pushing to main.
  • Installs dependencies.
  • Deploys the MkDocs site to GitHub Pages.

8️⃣ Enabling GitHub Pages

To finalize the deployment:

  1. Go to your repository Settings.
  2. Scroll to Pages.
  3. Under Build and Deployment, select GitHub Actions.
  4. If needed, set gh-pages as the deployment branch.

Your site will be available at:

https://YOUR_USERNAME.github.io/mkdocs-demo/
Enter fullscreen mode Exit fullscreen mode

🔟 Deploying Updates

To deploy changes, commit and push updates:

git add --all git commit -m "Update documentation" git push origin main
Enter fullscreen mode Exit fullscreen mode

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)