Skip to content

MkDocs Deployment Documentation

This document outlines the process for deploying MkDocs documentation to GitHub Pages using a GitHub Actions workflow. The deployment process is triggered on specific events, ensuring that updates to the documentation are reflected automatically.

GitHub Actions Workflow: docs_deploy.yml

Overview

This workflow automates the deployment of MkDocs-generated documentation to GitHub Pages. It triggers on changes to the docs/ folder, updates to the mkdocs.yml configuration file, or tags starting with docs-v.

Triggers

  • Push:
  • To the dev branch.
  • Tags matching the pattern docs-v*.
  • Changes in the docs/ folder or the mkdocs.yml file.
  • Pull Request targeting the dev branch.
  • Manual Trigger via workflow_dispatch.

Jobs

1. deploy-mkdocs

  • Runs on: ubuntu-latest
  • Conditional Execution: The job runs if the event is a qualifying push, pull request, or manual trigger.
  • Steps:
  • Checkout Code: Fetches the code from the repository.
  • Check for Changes:
    • Compares the latest commit with the previous one to detect changes in the docs/ folder or the mkdocs.yml file.
    • Sets the deploy_docs environment variable to true if changes are found.
  • Set up Python: Installs Python 3.11.
  • Install MkDocs Material: Installs MkDocs and the Material theme.
  • Deploy to GitHub Pages: Uses the mkdocs gh-deploy command to publish the documentation.

Notes

Key Features

  • Selective Deployment: Deploys only when changes are detected in relevant files, optimizing workflow execution.
  • Trigger Flexibility: Supports both automatic and manual deployment triggers.

Requirements

  • Ensure mkdocs.yml is correctly configured for your project.
  • Include the docs/ folder in your repository with the documentation source files.
  • GitHub Secrets for repository permissions are managed automatically.

Conclusion

This workflow ensures that your documentation is always up-to-date with minimal manual intervention. It integrates seamlessly with GitHub Pages and the MkDocs Material theme, providing a robust solution for managing project documentation.