Deploying MkDocs on GitHub Pages with DevContainers

🚀 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

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

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:

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/

---

🔟 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.