Skip to content

Week 02: Automating MkDocs Deployment with Git-Based Author Attribution

Overview

This week focused on transforming our MkDocs documentation setup from a manually deployed system into a fully automated documentation pipeline with contributor attribution.

The primary goals were:

  • Automatically deploy MkDocs to GitHub Pages on every commit
  • Display page authors based on Git commit history
  • Enable multiple contributors to independently publish weekly content
  • Improve documentation readability using Material theme features and Markdown extensions

By the end of the week, we achieved a CI/CD-enabled documentation workflow where content updates are published automatically and authorship is derived directly from version control.

Technical Work Completed

1. MkDocs Material Configuration

We standardized the documentation theme using MkDocs Material and added UI/UX enhancements such as navigation tabs, sectioned sidebars, code-copy buttons, and edit actions.

Theme configuration:

theme:
  name: material
  custom_dir: overrides
  palette:
    scheme: slate
    primary: blue
    accent: cyan
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - content.code.copy
    - content.action.edit

2.Git-Based Author Attribution

To support contributor attribution, we integrated the mkdocs-git-authors-plugin. The final configuration ensures that authors are determined strictly from the Git history of each individual Markdown file:

plugins:
  - search
  - git-authors:
      strict: true
      show_contribution: false

3. Markdown Enhancements

To improve technical readability and structure, several Markdown extensions were enabled:

markdown_extensions:
  - admonition
  - toc:
      permalink: true
  - tables
  - pymdownx.superfences
  - pymdownx.details
  - pymdownx.highlight

These provide collapsible sections, syntax highlighting, tables, admonitions, and automatic table-of-contents generation.

3. CI/CD Automation

A CI/CD pipeline was implemented to fully automate documentation deployment. On every push to the main branch: 1. The repository is checked out with complete Git history 2. Python and MkDocs dependencies are installed 3. The documentation site is built 4. The site is deployed automatically using mkdocs gh-deploy

As a result, any committed documentation change is immediately reflected on the live site, eliminating all manual deployment steps.

Challenges Faced

Accurate Author Attribution

Initially, contributors appeared on pages they did not directly author. This was resolved by enabling strict file-level attribution and disabling page-level contribution tracking. This ensured that authorship is derived exclusively from each Markdown file’s Git history.

Theme Customization

Because Material for MkDocs bundles its templates within the installed package, they are not locally editable by default.

To ensure upgrade-safe customization, an overrides/ directory was introduced, leveraging MkDocs’ theme inheritance mechanism to extend or override Jinja2 template blocks without modifying upstream theme files.

Outcomes

By the end of Week 02, the team successfully delivered: - Fully automated MkDocs deployment via CI/CD - Git-based per-page author attribution - A structured multi-contributor documentation workflow - Enhanced navigation and UI through Material theme features

The documentation platform is now scalable, contributor-friendly, and requires zero manual deployment effort. This provides a strong foundation for weekly reporting and future project documentation.