DEV Community

John  Ajera
John Ajera

Posted on

2

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

Image of AssemblyAI tool

Transforming Interviews into Publishable Stories with AssemblyAI

Insightview is a modern web application that streamlines the interview workflow for journalists. By leveraging AssemblyAI's LeMUR and Universal-2 technology, it transforms raw interview recordings into structured, actionable content, dramatically reducing the time from recording to publication.

Key Features:
🎥 Audio/video file upload with real-time preview
🗣️ Advanced transcription with speaker identification
⭐ Automatic highlight extraction of key moments
✍️ AI-powered article draft generation
📤 Export interview's subtitles in VTT format

Read full post

Top comments (0)

Image of Timescale

Timescale – the developer's data platform for modern apps, built on PostgreSQL

Timescale Cloud is PostgreSQL optimized for speed, scale, and performance. Over 3 million IoT, AI, crypto, and dev tool apps are powered by Timescale. Try it free today! No credit card required.

Try free

👋 Kindness is contagious

Dive into an ocean of knowledge with this thought-provoking post, revered deeply within the supportive DEV Community. Developers of all levels are welcome to join and enhance our collective intelligence.

Saying a simple "thank you" can brighten someone's day. Share your gratitude in the comments below!

On DEV, sharing ideas eases our path and fortifies our community connections. Found this helpful? Sending a quick thanks to the author can be profoundly valued.

Okay