Configure MkDocs infrastructure with Material theme and i18n support

[Copilot]

Implements WP-243B: establishes MkDocs build infrastructure as part of Sphinx→MkDocs migration (ADR-002). Sphinx sources in src/ preserved for rollback.

Configuration

• mkdocs.yml: Material theme with navigation, search, dark mode, code highlighting
• i18n plugin: folder-based localization (content/en/, content/uk/)
• Dependencies via uv: mkdocs, mkdocs-material, mkdocs-static-i18n, pymdown-extensions

Content Structure

Created stub directories for migration pipeline:

• content/en/index.md - placeholder for WP-243A content conversion
• content/uk/index.md - stub for future Ukrainian translation
• Translation status documented in content/uk/.translation-status.md

Automation

GitHub Actions workflow (.github/workflows/deploy-docs.yml):

- name: Install uv
  uses: astral-sh/setup-uv@v3
- name: Build documentation  
  run: uv run mkdocs build --strict

Deploys to GitHub Pages on main branch push.

Documentation

Updated README.rst with MkDocs build commands:

uv sync
uv run mkdocs serve  # http://127.0.0.1:8000
uv run mkdocs build  # outputs to ./site/

Screenshots

English (light mode)

Ukrainian (light mode)

Dark mode

---

Dependencies: Requires WP-243A (content conversion) for full functionality
Related: ADR-002, WP-243C (cleanup)

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• astral.sh
  • Triggering command: /usr/bin/curl curl -LsSf REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[WP] MkDocs Setup and Configuration</issue_title>
<issue_description>[//]: # (WP-243B-mkdocs-setup.md)

Work Package 243B: MkDocs Setup and Configuration

Assignment Date: 2026-01-28
Assigned To: project-administrator (Claude Code)
Assigned By: project-manager (Claude Chat)
Priority: High
Estimated Complexity: Medium
Parent Issue: #243 (Static Site Generator Migration to MkDocs - ADR-002)

---

Objective

Configure MkDocs with Material theme, set up multilingual support for English/Ukrainian, add project dependencies using uv, and establish automated deployment workflow.

---

Backstory

With content converted to Markdown (WP-243A), this sub-package establishes the MkDocs infrastructure. This includes configuration, theme setup, localization support, dependency management via uv, and GitHub Actions deployment. The goal is to have a fully functional MkDocs site that can build and deploy while src/ remains as fallback.

---

Branch Instructions

Work on feature branch:

git fetch origin
git checkout feature/wp-mkdocs-migration

All work happens on feature/wp-mkdocs-migration branch. Do NOT merge to main until parent #243 is complete.

---

Definition of Done

• mkdocs.yml configuration file created at repository root
• MkDocs dependencies added to pyproject.toml using uv
• Material theme configured with navigation, search, and dark mode
• mkdocs-static-i18n plugin configured for English/Ukrainian
• Ukrainian content structure (content/uk/) created (full or stub as appropriate)
• Site builds successfully with uv run mkdocs build
• Local preview works with uv run mkdocs serve
• GitHub Actions workflow created for automated deployment
• Documentation updated (README sections for MkDocs)
• Changes committed with clear message

---

Context

Reference Documents:

• ADR-002: Static Site Generator Replacement (docs/ADR-002-ssg-replacement.md)
• Parent Issue: [WP]: Static Site Generator Migration to MkDocs #243 (MkDocs Migration)
• Project uses uv for dependency management (not pip)

Key Context:

• This is sub-package 2 of 3 for WP-243
• Depends on WP-243A completion (content must be converted)
• Independent from WP-243C (which happens after this)
• Content is in content/en/ as .md files
• src/ directory still exists as fallback
• Project uses uv for all Python dependency management

What This Covers:

• MkDocs configuration
• Material theme setup
• Multilingual (i18n) configuration
• Dependency management via uv
• GitHub Actions deployment
• Ukrainian content structure
• Documentation updates

What This Doesn't Cover:

• Content conversion (that was WP-243A)
• Removing src/ or Sphinx (that's WP-243C)
• Modifying course content

---

Deliverables

1. MkDocs Configuration

Create mkdocs.yml at repository root:

site_name: Python for Web Developers
site_url: https://openroost.github.io/pymastery-vp/
repo_url: https://github.com/OpenRoost/pymastery-vp
repo_name: OpenRoost/pymastery-vp
edit_uri: edit/main/content/

docs_dir: content
site_dir: site

theme:
  name: material
  language: en
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - navigation.tracking
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
  palette:
    # Light mode
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    # Dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  font:
    text: Roboto
    code: Roboto Mono

plugins:
  - search:
      lang:
        - en
        - uk
  - i18n:
      docs_structure: folder
      fallback_to_default: true
      reconfigure_material: true
      reconfigure_search: true
      languages:
        - locale: en
          name: English
          build: true
          default: true
        - locale: uk
          name: Українська
          build: true

markdown_extensions:
  # Admonitions
  - admonition
  - pymdownx.details
  
  # Code blocks
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.superfences
  - pymdownx.inlinehilite
  
  # Content features
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - attr_list
  - md_in_html
  - def_list
  
  # Navigation
  - toc:
      permalink: true
      toc_depth: 3

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/OpenRoost/pymastery-vp
      name: GitHub Repository
  generator: false  # Hide "Made with Material for MkDocs" footer

copyright: >
  Copyright © 2024 Op...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes OpenRoost/pymastery-vp#256

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

[Copilot]

Pull request overview

Configures MkDocs with the Material theme and i18n support, wires it into the existing Python project via uv, and sets up GitHub Pages deployment for the new documentation site.

Changes:

• Adds MkDocs/MkDocs-Material/mkdocs-static-i18n/pymdown-extensions as project dependencies and locks their concrete versions in uv.lock.
• Introduces mkdocs.yml plus stub English and Ukrainian content, including a translation status document for the Ukrainian locale.
• Adds a GitHub Actions workflow to build and deploy the MkDocs site to GitHub Pages, updates .gitignore for the build output, and documents MkDocs usage in README.rst.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
uv.lock	Locks in the new MkDocs-related dependency graph (mkdocs, mkdocs-material, mkdocs-static-i18n, pymdown-extensions and their transitive deps) for reproducible builds.
pyproject.toml	Declares MkDocs and related plugins as first-class project dependencies to be managed via uv.
mkdocs.yml	Defines the MkDocs configuration: Material theme, English/Ukrainian i18n via mkdocs-static-i18n, search, palettes, and Markdown extension stack.
content/en/index.md	Creates an English landing page stub describing the course and noting that full content will arrive after the Sphinx→Markdown migration.
content/uk/index.md	Adds a Ukrainian landing stub that indicates translation is in progress and links back to the English version.
content/uk/.translation-status.md	Documents the status, contribution process, and guidelines for Ukrainian translations in the content/uk/ subtree.
README.rst	Adds a new section explaining how to build and serve the MkDocs documentation with uv, and documents the new content//mkdocs.yml-based structure.
.gitignore	Ignores the MkDocs build output directory site/ to keep generated artifacts out of version control.
.github/workflows/deploy-docs.yml	Adds a Pages-oriented workflow to build the MkDocs site with uv on CI and deploy it to GitHub Pages on pushes to main.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.